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Program and CL Command APIs 


The Program and CL Command APIs create programs, retrieve program information, list and retrieve 
module information, activate bound programs, resolve pointers to exports, and retrieve command 
information. 


Before using the Create Program API, you should have some MI programming experience and understand 
the concepts in the iSeries Machine Interface Instructions, which provides detailed descriptions of the 


iSeries machine interface instruction fields and the formats of those fields. 


The Program and CL Command APIs are: 


Activate Bound Program (QleActBndPgm) activates the specified bound program or service 


program and all dependent service programs, and then initalizes the newly activated service 
programs. 


Add Associated Space Entry (QbnAddAssociatedSpaceEntry) is used by a compiler preprocessor to 
put data into the associated space of the created module. 

Add Bindtime Exit (QbnAddBindtimeExit) is used by a compiler preprocessor to define an exit 
program that can be called when a created module is bound into an ILE program. 

Add Extended Attribute Data (QbnAddExtendedAttributeData) is used by a preprocessor to set the 
extended attribute field of a created module. 

Add Preprocessor Level Data (QbnAddPreProcessorLevelData) is used to set the level of the 
preprocessor used to create a module. 


Call Service Program Procedure (QZRUCLSP) allows an unbound call to an ILE procedure 
exported by a service program. 


Check Command Syntax (QCMDCHK) performs syntax checking for a single command, and 
optionally prompts for the command. 

Create Program (QPRCRTPG) converts the symbolic representation of a machine interface (MI) 
program into a program object. 


End Preprocessor (QbnEndPreProcessor) must be called by every preprocessor after the output 
source file and preprocessor information is created. It records that a preprocessor was called. 


Execute Command (QCMDEXC) runs a single CL command or can be used to run a command 
from within a high-level language or CL program. 


Get Export (QleGetExp) allows the caller to resolve a pointer to an export (either data or 
procedure) either by name or export number. The pointer is materialized for the specified 
activation. 

Java™) Virtual Machine Debug Interface (IVMDID) is a programming interface used by debuggers 
and other programming tools. It provides a way both to inspect the state and to control the 


execution of applications running in the Java™) Virtual Machine. 
2Java(™) Virtual Machine Profiler Interface (IVMPI) is intended for tools vendors to develop 


profilers that work in conjunction with Sun's Java virtual machine ‘mplementaion Manet 


2Java(™) Debug Wire Protocol (JDWP) is the protocol used for communication between a 


debugger and the Java virtual machine (VM) that it debugs a 


List ILE Program Information (QBNLPGMI) gives information about Integrated Language 
Environment * (ILE *) programs, similar to the Display Program (DSPPGM) command. 


e List Module Information (QBNLMODI) API lists information about modules similar to the Display 
Module (DSPMOD) command. The information is placed in a user space specified by you. 


e List Service Program Information (QBNLSPGM) gives information about service programs, 
similar to the Display Service Program (DSPSRVPGM) command. 


e Process Commands (QCAPCMD) performs command analyzer processing on command strings. 


e Replace Command Exit Program (QCARPLCM) may be used as the exit program for the 
QIBM_QCA_CHG_COMMAND for any command. 


e Retrieve Associated Space (QbnRetrieveAssociatedSpace) retrieves data stored with the 
QbnAddAssociatedSpaceEntry API. 


e Retrieve Command Definition (QCDRCMDD) API retrieves the command definition source for a 
given command in XML tag language format. 


e@ Retrieve Command Information (QCDRCMDI) retrieves information from a command definition 
object. 


e Retrieve Module Information (QBNRMODJ API lets you retrieve module information and place it 
into a single variable in the calling program similar to the information returned using the Display 
Module (DSPMOD) command. The amount of information returned is limited to the size of the 
variable. 

e Retrieve Program Associated Space (QCLRPGAS) retrieves information from the associated space 
of a user-state, user-domain program. 


e Retrieve Program Information (QCLRPGMD) retrieves program information similar to the Display 
Program (DSPPGM) command. 


e Retrieve Prompt Override (QPTRTVPO) calls the prompt override program for a specified 
command and returns the prompt override command string from the prompt override program. 


e Retrieve Service Program Information (QBNRSPGM) retrieves service program information 
similar to the information returned using the Display Service Program (DSPSRVPGM) command. 


e Scan for String Pattern (QCLSCAN) is used to scan a string of characters to see if the string 
contains a pattern. 


e@ Start Preprocessor (QbnStartPreProcessor) must be called first by every compiler preprocessor that 
has data to be processed during module creation. 


e Store Program Associated Space (QCLSPGAS) stores information in the associated space of a 
user-state, user-domain program. 


The Program and CL Command exit programs are: 


e Command Analyzer Change is called when the command for which it is registered is processed. 


e Command Analyzer Retrieve is called when the command for which it is registered is processed. 


Top | APIs by category 


Activate Bound Program (QleActBndPgm) API 


Required Parameter: 
Pointer to bound program PTR(SYP) 
Omissible Parameter Group: 


Activation mark Binary(4) 
Activation information Char(*) 
Length of activation information Binary(4) 
Error code Char(*) 


Returned Value: 


Activation mark Binary(4) 


Default Public Authority: *USE 


Service Program: QLEAWI 


Threadsafe: Yes 


The Activate Bound Program (QleActBndPgm) API activates the bound program or service program 
specified by the pointer to bound program parameter if it is not already active. All dependent service 
programs are activated, and all initialization of the newly activated service programs is done. 


Initialization may consist of calling user procedures. All unhandled exceptions that occur during 
initialization will be percolated to the caller of QleActBndPgm; they will never be returned in the error 
code parameter. QleActBndPgm will never move the resume cursor for the exception. Therefore, it is 
possible for the caller of QleActBndPgm to handle an exception and resume initialization. 


This API is normally used in conjunction with the Get Export (QleGetExp) API. First, you activate a 
service program using QleActBndPgm, and then later you use QleGetExp to retrieve pointers to procedures 
and data from that activation. 


The QleActBndPgm API may not be called in a secondary thread of a Common Platform Architecture 
(CPA) application. 


Required Parameter 


Pointer to bound program 
INPUT; PTR(S YP) 


A system pointer to the program or service program to be activated. 


Omissible Parameter Group 


Activation mark 
OUTPUT; BINARY(4) 


The entity uniquely identifying the activation within the current job. 
Activation information 
OUTPUT; CHAR(*) 


The structure that contains additional activation information. The format of this structure is shown 
in Format of Activation Information. If activation information is specified, the length of activation 
information parameter must also be specified. The storage for activation information must be on a 
16-byte boundary. 


Length of activation information 
INPUT; BINARY(4) 


The length of the activation information. If the length is larger than the size of the storage for 
activation information, the results may not be predictable. The minimum length is 8 bytes. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Activation mark 
OUTPUT; BINARY(4) 


This API returns the value for the activation mark parameter. 


Format of Activation Information 


| Offset 
| Dec Hex /|Type Field 


[ 31 [| IF |CHARG) [Flags 


Field Descriptions 


Activation group mark. An entity uniquely identifying the activation group within the current job. 
Activation mark. An entity uniquely identifying the activation within the current job. 
Flags _ Bit values 


BIO 0 The program or service program was not already activated. 


I The program or service program was already activated. 


Bit 1-7 Reserved 


Bytes available. The length of all available information that could be returned. Bytes available can be 
greater than the length of activation information parameter. If it is greater, the information returned is 
truncated to the length specified. 


Bytes returned. The length of all information returned. The value of the bytes returned field is always less 


than or equal to the length returned in the bytes available field. 


Reserved. An area of reserved storage. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CI1E E Required parameter &1 omitted. 

CPF3C24 E Length of the receiver variable is not valid. 
CPF3C3A E Value for parameter &2 for API &1 not valid. 
CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
MCH3402 E The argument being tested is not an address. 
MCH4421 E At least one field in the allocation strategy is not valid. 
MCH4430 E The exit priority value provided for &1 is not valid. 


API Introduced: V3R6 
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Add Associated Space Entry 
(QbnAddAssociatedSpaceEntry) API 


Required Parameter Group: 


Associated space identifier Char(10) 
Associated space entry data Char(*) 
Length of associated space entry data Binary(4) 
Options Char(1) 
Error code Char(*) 


Default Public Authority: *USE 


Service Program: QBNPREPR 


Threadsafe: No 


The Add Associated Space Entry (QbnAddAssociatedSpaceEntry) API may be used by a compiler 
preprocessor to put data in the associated space of the created module. 


Authorities and Locks 


None 


Required Parameter Group 


Associated space identifier 
INPUT; CHAR(10) 


The associated space identifier has the following special value: 


*PREPROC Identifies the type of data being stored in the created module. The special value 
must be left-justified and padded with blanks. 


Associated space entry data 
INPUT; CHAR(*) 


The data to be placed into the associated space of the created module. The format of this data is 
specified by the user. This data will be copied into an ILE bound program or ILE service program 
and is available for use when the program is running. The QbnRetrieveAssociatedSpace API is 
used to retrieve this data from an ILE program or service program. 


Length of associated space entry data 
INPUT; BINARY(4) 


The length of the data contained in the associated space entry data parameter. 
Options 
INPUT; CHAR(1) 


You must specify one of the following special values. If more than one associated space entry is 
defined as extendable during preprocessing, the module will not be created. If DB2 UDB for 
iSeries SQL statements are contained in the input source file, option 2 cannot be specified. 


I The associated space entry will not be extendable. 


2 The associated space entry can be extended. The associated space expands as data is stored 
in the associated space using QbnAddAssociatedSpaceEntry API. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF5CA2 E &1 is not a valid associated space identifier parameter. 
CPF5CA3 E Option &1 is not valid. 

CPF5CA4 E Error occurred while addressing API Parameter. 

CPF5D22 E Not able to locate internal data. 

CPF5D24 E Unexpected error occurred during preprocessor processing. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
API Introduced: V3R1 
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Add Bindtime Exit (QbnAddBindtimeExit) API 


Required Parameter Group: 


Qualified exit program name Char(20) 
Exit program data Char(*) 
Length of exit program data Binary(4) 
Error code Char(*) 


Default Public Authority: *USE 


Service Program: QBNPREPR 


Threadsafe: No 


The Add Bindtime Exit (QbnAddBindtimeExit) API may be used by a compiler preprocessor to define an 
exit program that is called when the created module is bound into a ILE program. 


Authorities and Locks 


None 


Required Parameter Group 


Qualified exit program name 
INPUT; CHAR(20) 
The qualified name of the exit program to be called when the created module is bound into an ILE 
program. The first 10 characters contain the program name, which is left-justified and padded with 


blanks. The second 10 characters contain the name of the library where the exit program is located 
and is left-justified and padded with blanks. 


The library name can be specified with the following special value: 


*LIBL The library list. 


The exit program is passed five parameters when called. The first two parameters are the exit 
program data and the exit program data length. The third parameter is a reserved CHAR(10). The 
fourth and fifth parameters are both reserved BINARY (4). 
The exit program data being used in this API is defined by the user. 

Exit program data 
INPUT; CHAR(*) 


This data is copied into the output source file member by the QbnEndPreProcessor API. When the 


exit program is called at ILE program creation time, a copy of the data is passed. The format of this 
data is specified by the supplier of the exit program. This data is ignored if the length of data to be 
passed to the length of exit program data parameter value is 0. 


Length of exit program data 
INPUT; BINARY(4) 


The length of the data contained in the exit program data parameter. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF5CA4 E Error occurred while addressing API Parameter. 
CPF5CEA E Library value &1 is not valid. 

CPF5D22 E Not able to locate internal data. 

CPF5D24 E Unexpected error occurred during preprocessor processing. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V3R1 
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Add Extended Attribute Data 
(QbnAddExtendedAttributeData) API 


Required Parameter Group: 


1 Extended attribute data Input Char(20) 
2 Error code VO Char(*) 


Default Public Authority: *USE 


Service Program: QBNPREPR 


Threadsafe: No 


The Add Extended Attribute Data (QbnAddExtendedAttributeData) API may be used by a preprocessor to 
set the extended attribute field of the created module. The attribute field is part of the service related 
attributes of a module object. Because multiple preprocessors may be called in the path of module creation, 
and because each module only has a single attribute, only the initial preprocessor is allowed to set the 
extended attribute. 


Authorities and Locks 


None 


Required Parameter Group 
Extended attribute data 
INPUT; CHAR(20) 


The extended attribute data to be set in the created module. This data further describes the object, 
such as CLP for a CL program or PF for a file. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 


CPF24B4 E Severe error while addressing parameter list. 


CPF3C90 E 
CPF3CF1 E 
CPF5CA4 E 
CPF5D22 E 
CPF5D24 E 
CPF9872 E 


Literal value cannot be changed. 

Error code parameter not valid. 

Error occurred while addressing API Parameter. 

Not able to locate internal data. 

Unexpected error occurred during preprocessor processing. 


Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V3R1 


Top | Program and CL Command APIs | APIs by category 


Add Preprocessor Level Data 
(QbnAddPreProcessorLevelData) API 


Required Parameter Group: 


1 Preprocessor level data Input Char(6) 
2 Error code VO Char(*) 


Service Program: QBNPREPR 


Threadsafe: No 


The Add Preprocessor Level Data (QbnAddPreProcessorLevelData) API may be used to set the level of the 
preprocessor used to create the module. 


Authorities and Locks 


None 


Required Parameter Group 


Preprocessor level data 
INPUT; CHAR(6) 


A description of the current preprocessor environment. The preprocessor-level data is specified 
with version, release, and modification information. This string must contain 6 characters of the 
form VxRyMz where x, y, and z are single digits. The valid values are between 0 and 9. The 
preprocessor-level data is an extension of the product number. This preprocessor-level data can 
then be used to show a different environment from that of the compiler. The preprocessor-level data 
must be less than or equal to the VxRyMz string of characters specified by the compiler, or module 
creation will fail. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 


CPF24B4 E Severe error while addressing parameter list. 


CPF3C90 E 
CPF3CF1 E 
CPF5CA4 E 
CPF5D22 E 
CPF5D24 E 
CPF5D29 E 
CPF9872 E 


Literal value cannot be changed. 

Error code parameter not valid. 

Error occurred while addressing API Parameter. 

Not able to locate internal data. 

Unexpected error occurred during preprocessor processing. 
Level data specified is not valid. 


Program or service program &1 in library &2 ended. Reason code &3. 
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Call Service Program Procedure (QZRUCLSP) 
API 


Required Parameter Group: 


Qualified service program name Char(20) 
Export Name Char(*) 
Return Value Format Binary(4) 
Parameter Formats Array(*) of 
Binary(4) 
Number of Parameters Binary(4) 
Error code CHAR(*) 


Optional Parameters: 


Return Value 
Parameter 1 
Parameter 2 
Parameter 3 
Parameter 4 
Parameter 5 
Parameter 6 
Parameter 7 


Default Public Authority: *USE 


Threadsafe: No 


The Call Service Program Procedure (QZRUCLSP) API allows an unbound call to an ILE procedure 
exported by a service program. 


The name of the service program, and the name of the exported procedure are passed in as parameters. This 
API runs in the callers activation group and if the specified service program also specifies that it run in the 
caller's activation group, it too will run in the same group. All dependent service programs are activated, 
and all initialization of the newly activated service programs is done. 


Since the QZRUCLSP API has no way of determining the parameters that the called procedure expects, the 
layout of those parameters must be described by the caller in a "Parameter Format" array. 


All of the parameter values given to this API to be subsequently passed to the procedure are passed by 
reference. 


This API does not support calling procedures that have been defined using "#pragma argopt". 


Authorities and Locks 


Service Program Authority 
*EXECUTE 

Service Program Library Authority 
*EXECUTE 

Service Program Lock 
*SHRRD 


Required Parameter Group 
Qualified service program name 
INPUT; CHAR(20) 


The name of the service program for which the information is to be listed. The first 10 characters 
contain the service program name. The second 10 characters contain the name of the library where 
the service program is located. 


The library name can be these special values: 
*CURLIB The job's current library 


*LIBL The library list 


Export name 
INPUT; CHAR(*) 


A null terminated string containing the name of the exported identifier. The name is matched 
exactly, without CCSID conversion or folding to uppercase. 


Return Value Format 
INPUT; BINARY(4) 


The format of the returned data. 
This value must be one of the following: 
0 The procedure does not return a value. The "Return Value” parameter is ignored. 


I The procedure returns an integer. The "Return Value" parameter should address a location to 
receive a BINARY{(A4) value. 


2 The procedure returns a pointer. The "Return Value” parameter should address a location to 
receive a 16 byte pointer. 


3 The procedure returns an integer and the "errno" return value set by many program calls. The 
"Return Value" parameter should address a location to receive two BINARY(A4) values. The 
first is the four byte return value, and the second is the four byte errno value. 


Parameter Formats 


INPUT; ARRAY(*) of BINARY(4) 


The format of the parameters. This length of this array is specified in the "Number of parameters" 
value. 


Each array entry should be one of the following: 
I The parameter is a BINARY (4) argument to be passed to the procedure by value. 


2 The parameter is a pointer value. 


Number of parameters 
INPUT; BINARY(4) 
The number of parameters that will be passed to the procedure. Up to seven parameters are 
supported. 
Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Optional Parameters 


Return value 
OUTPUT; CHAR(*) 
For procedures that return a value, this parameter points to the space to receive the data. 
If this parameter is not passed, or is passed using a null pointer, no value is returned regardless of 
the value of the "Return value format" parameter. 
Parameter 1 
1/0; CHAR(*) 
The first parameter passed to the procedure. If the corresponding entry in the parameter format 


array is a 1, this parameter should address a BINARY (4) value. If the corresponding entry in the 
parameter format array is a 2, this parameter should address the storage being referenced. 


If the parameter format array indicates that a parameter should be passed to the exported procedure 
in this position, but Parameter 1 is not passed to the QZRUCLSP API, then zero or a null pointer, 
depending on the parameter format array entry, is passed to the procedure. 


Parameter 2 
1/0; CHAR(*) 
The second parameter passed to the procedure. If the corresponding entry in the parameter format 


array is a 1, this parameter should address a BINARY (4) value. If the corresponding entry in the 
parameter format array is a 2, this parameter should address the storage being referenced. 


If the parameter format array indicates that a parameter should be passed to the exported procedure 
in this position, but Parameter 2 is not passed to the QZRUCLSP API, then zero or a null pointer, 


depending on the parameter format array entry, is passed to the procedure. 
Parameter 3 
1/0; CHAR(*) 


The third parameter passed to the procedure. If the corresponding entry in the parameter format 
array is a 1, this parameter should address a BINARY (4) value. If the corresponding entry in the 
parameter format array is a 2, this parameter should address the storage being referenced. 


If the parameter format array indicates that a parameter should be passed to the exported procedure 
in this position, but Parameter 3 is not passed to the QZRUCLSP API, then zero or a null pointer, 
depending on the parameter format array entry, is passed to the procedure. 


Parameter 4 
1/O; CHAR(*) 


The fourth parameter passed to the procedure. If the corresponding entry in the parameter format 
array is a 1, this parameter should address a BINARY (4) value. If the corresponding entry in the 
parameter format array is a 2, this parameter should address the storage being referenced. 


If the parameter format array indicates that a parameter should be passed to the exported procedure 
in this position, but Parameter 4 is not passed to the QZRUCLSP API, then zero or a null pointer, 
depending on the parameter format array entry, is passed to the procedure. 


Parameter 5 
1/O; CHAR(*) 


The fifth parameter passed to the procedure. If the corresponding entry in the parameter format 
array is a 1, this parameter should address a BINARY (4) value. If the corresponding entry in the 
parameter format array is a 2, this parameter should address the storage being referenced. 


If the parameter format array indicates that a parameter should be passed to the exported procedure 
in this position, but Parameter 5 is not passed to the QZRUCLSP API, then zero or a null pointer, 
depending on the parameter format array entry, is passed to the procedure. 


Parameter 6 
1/O; CHAR(*) 


The sixth parameter passed to the procedure. If the corresponding entry in the parameter format 
array is a 1, this parameter should address a BINARY (4) value. If the corresponding entry in the 
parameter format array is a 2, this parameter should address the storage being referenced. 


If the parameter format array indicates that a parameter should be passed to the exported procedure 
in this position, but Parameter 6 is not passed to the QZRUCLSP API, then zero or a null pointer, 
depending on the parameter format array entry, is passed to the procedure. 


Parameter 7 
1/O; CHAR(*) 


The seventh parameter passed to the procedure. If the corresponding entry in the parameter format 
array is a 1, this parameter should address a BINARY (4) value. If the corresponding entry in the 
parameter format array is a 2, this parameter should address the storage being referenced. 


If the parameter format array indicates that a parameter should be passed to the exported procedure 
in this position, but Parameter 7 is not passed to the QZRUCLSP API, then zero or a null pointer, 
depending on the parameter format array entry, is passed to the procedure. 


Usage Notes 


Since this API is implemented as a program, it adds an additional control boundary between the caller and 


the service program procedure. 


Any exceptions generated by the service program procedure are either returned in the error code structure, 


if provided, or resignalled to the caller. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CIDE 
CPF3C1EE 
CPF3C24 E 
CPF3C3A E 
CPF3C90 E 
CPF3CF1 E 
CPF3CF2 E 
MCH3402 E 
MCH4421 E 
MCH4422 E 
MCH4430 E 


Example 


The following is an example of a program calling the Qp0IGetAttr() API. That API takes the following 


parameters: 


Error Message Text 

Severe error while addressing parameter list. 
Length specified in parameter &1 not valid. 
Required parameter &1 omitted. 

Length of the receiver variable is not valid. 

Value for parameter &2 for API &1 not valid. 
Literal value cannot be changed. 

Error code parameter not valid 

Error(s) occurred during running of &1 API. 

The argument being tested is not an address. 

At least one field in the allocation strategy is not valid. 
&1 cannot be called in the default activation group. 


The exit priority value provided for &1 is not valid. 


int Qp0Ol1GetAttr 
(Qlg_Path_Name_T *Path_Name, 


Qp0l_AttrTypes_List_t *Attr_Array_ptr, 


char 
uint 
uint 
uint 
uint 


*Buffer_ptr, 
Buffer_Size_Provided, 

*Buffer_Size_Needed_ptr, 

*Num_Bytes_Returned_ptr, 
Follow_Symink, ...); 


The procedure returns an integer, and its parameters are pointer, pointer, pointer, integer, pointer, pointer, 
integer. The parameter format array for calling this procedure is 2, 2, 2, 1, 2, 2, 1. 


#include <QZRUCLSP.H> 


int main(int argc, char **argv) 
{ 
int rc; /* return code */ 
struct { 
Qlg_Path_Name_T lg; 
char *path; 
} Ilname; /* the path name parameter */ 


int attrreq[2]; /* the attributes requested */ 


char buffer[32]; /* returned information */ 

int needed; /* bytes needed a A 

int returned; /* bytes returned x 

int parm_format[7] = {2, 2, 2, 1, 2, 2, 1}; 

QZRUCLSP ("QPOLLIB2 QSYS ", /* SRVPGM */ 
"QOp01GetAttr", /* Procedure * / 
1, /* Return integer */ 
parm_format, /* parm formats */ 
ve /* Seven parms AY 
NULL, /* error code * / 
&XLC, /* return value / 
&lpath, /* pointer a A 
attrreq, /* pointer a 
buffer, /* pointer * / 
sizeof (buffer), /* integer / 
&needed, /* pointer iw A 
&returned, /* pointer */ 
0); /* integer */ 
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Check Command Syntax (QCMDCHK) API 


Required Parameter Group: 


1 Command string Char(*) 
2 Length of command string Packed(15,5) 


Optional Parameter: 


IGC process control Char(3) 


Default Public Authority: *USE 


Threadsafe: Yes. 
See Usage Notes for command considerations. 


The Check Command Syntax (QCMDCHK) API performs syntax checking for a single command, and 
optionally prompts for the command. The command is not run. If prompting is requested, the command 
string is returned to the calling program with the updated values as entered through prompting. The 
QCMDCHK API can be called from an HLL program. 
Typical uses of QCMDCHK are: 

e Prompt the user for a command and then store the command for later processing. 

e Determine the parameter values specified by the user. 

e Log the processed command. First, prompt with the QCMDCHK API, run with the Execute 

Command (QCMDEXC) API, and then log the processed command. 

Notes: 


1. Command strings in System/38 syntax can use the QCACHECK API. The QCACHECK API 
accepts the same parameters as QCMDEXC and QCMDCHK. 


2. The Process Commands (QCAPCMD) API also provides similar functions. 


Authorities and Locks 


Any Command 
*USE 


Required Parameter Group 


Command string 
1/0;CHAR(*) 


The command you want to check is entered as a character string. If the command contains blanks, it 
must be enclosed in apostrophes. The maximum length of the character string is 32,702 characters; 
delimiters (the apostrophes enclosing the string) are not counted as part of the string. 


Length of command string 
INPUT;PACKED(15,5) 


The length of the command string being passed. If the command string is passed as a quoted string, 
the command length is exactly the length of the quoted string. If the command string is passed in a 
variable, the command length is the length of the variable. 


Optional Parameter Group 
IGC process control 
INPUT:;CHAR(*) 


The IGC process control instructs the system to accept double-byte data. The only value supported 
is IGC. IGC must be entered using all uppercase letters. 


Usage Notes 


While this API is threadsafe, it should not be used to run a command that is not threadsafe in a job that has 
multiple threads. Use the Display Command (DSPCMD) command to determine whether a command is 
threadsafe. 


Error Messages 


Message ID Error Message Text 

CPEFO0005 E Returned command string exceeds variable provided length. 

CPF0006 E Errors occurred in command. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


xxxnnnn E Any escape message issued by any command may be returned. The messages listed 
previously are those issued by this API. Once the API has called the command 
analyzer, any message issued as an escape message may appear. 


API in existance prior to V1R3 


Top | Program and CL Command APIs | APIs by category 


Create Program (QPRCRTPG) API 


Required Parameter Group: 


Intermediate representation of the program Char(*) 
Length of intermediate representation of Binary(4) 
program 

Qualified program name Char(20) 
Program text Char(50) 
Qualified source file name Char(20) 
Source file member information Char(10) 
Source file last changed date and time Char(13) 
information 

Qualified printer file name Char(20) 


Starting page number Binary(4) 
Public authority Char(10) 
Option template Char(*) 

Number of option template entries Binary(4) 


Optional Parameter: 


13 Error code 


Default Public Authority: *USE 


Threadsafe: No 


The Create Program (QPRCRTPG) API converts the symbolic representation of a machine interface (MI) 
program into an OPM program object. This symbolic representation is known as the intermediate 
representation of a program. 


The QPRCRTPG API creates a program object that resides in the *U.SER domain and runs in the *USER 
state. If you want the program object to be temporary, you must do one of the following: 
e Delete the object when you no longer need it. 
e Create the object in the QTEMP library, and let the system delete the object automatically when the 
job ends. 
You can specify program objects created with the QPRCRTPG API in CL commands that process objects 
of type *PGM. For example, you can: 


e Save and restore program objects using the Save Object (SAVOBJ) and Restore Object (RSTOBJ) 
commands. 


Delete program objects using the Delete Program (DLTPGM) command. 
Run program objects using the Call (CALL) command. 
Rename program objects using the Rename Object (RNMOBJ) command. 


Move program objects to a different library using the Move Object (MOVOBJ) command. 


Note: MI instructions that reference system-domain or write-protected objects fail at security levels 40 and 
50. At those levels, you must use APIs to work with the objects. 


Authorities and Locks 


Program Authority 
*ALL. Required only if the program already exists and the option value *REPLACE is specified. 

Program Library Authority 
*CHANGE 

Printer File Authority 
*USE 

Printer File Library Authority 
*USE 

Source File Authority 
*USE 

Source File Library Authority 
*USE 


Required Parameter Group 


Intermediate representation of the program 
INPUT; CHAR(*) 
A string containing the intermediate representation of the program to be processed by the 
QPRCRTPG API. See Program Syntax. 


Length of intermediate representation of program 
INPUT; BINARY(4) 


The size, in bytes, of the intermediate representation of the program. 
Qualified program name 
INPUT; CHAR(20) 
The name and library of the program to be created or replaced. The first 10 characters contain the 


program name, and the second 10 characters contain the name of the library where the program is 
located. The special value *CURLIB may be used for the library name. 


Program text 
INPUT; CHAR(S50) 


Text that briefly describes the program. 
Qualified source file name 
INPUT; CHAR(20) 


The name and library containing the source program. The first 10 characters contain the source file 
name, and the second 10 characters contain the name of the library where the file is located. This 


places the value in the program object's service description. The special value *NONE may be used 
for the source file name. If you specify *NONE, no source file information is placed in the program 
object's service description. A special value, such as *LIBL, is not valid for the source file library. 


Source file member information 
INPUT; CHAR(10) 
The file member containing the source program. This places the value in the program object's 
service description. 
This value must be blanks if you specify *NONE as the source file name. 
Source file last changed date and time information 
INPUT; CHAR(13) 


The date and time the member of the source file was last updated. The format of this field is in the 
CY YMMDDHHMMSS format, where: 


C Century, where 0 indicates years 19xx and 1 indicates years 20xx. 
YY Year 

MM Month 

DD Day 

HH Hour 

MM Minute 

SS Second 


This places the value in the program object's service description. 


This value must be blank if you specify *NONE for the source file name parameter. 
Qualified printer file name 
INPUT; CHAR(20) 
The name and library containing the printer file used to generate listings. The first 10 characters 


contain the printer file name, and the second 10 characters contain the name of the library where 
the file is located. The only special values supported for the library name are *LIBL and *CURLIB. 


This value is ignored if you specify *NOLIST for the generate listing option (see Values for the 
Option Template Parameter). 


Starting page number 
INPUT; BINARY(4) 


The first page number to be used on listings. This value should be between 1 and 9999; otherwise, 
the API uses 1. 


This value is ignored if you specify *NOLIST for the generate listing option (see Values for the 
Option Template Parameter). 


Public authority 
INPUT; CHAR(10) 


The authority you give the users who do not have specific private authorities to the object, and 
where the user's group has no specific authority to the object. 


The values allowed are: 
*CHANGE 
*ALL 
*USE 
*EXCLUDE 


The name of an authorization list 


Option template 
INPUT; CHAR(*) 


This is an array of options. You can specify between 0 and 16 values. Each entry contains a 
CHAR(11) value as described in Values for the Option Template Parameter. 


Number of option template entries 
INPUT; BINARY(4) 


The number of option template entries. 


The value must be between 0 and 16. 


Optional Parameter 


Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error code 


parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Values for the Option Template Parameter 


When you are using the QPRCRTPG API, you can specify a value in the option template. Only one value 
per option should be specified. If you specify more than one, the system only uses the first one. If you 
specify no value for a given option, the system uses the default value (underlined). 


Create program object 


Creates a program object. 
The values allowed are: 


*GEN Generates a program and places the program in the appropriate library. 


*NOGEN No program is generated. The syntax of the intermediate representation of the 
program is checked, and if the generate listing option is *LIST, a listing is produced. 


Replace program 


Replaces the existing program if a program by the same name already exists in the specified 
library. 


The values allowed are: 


*NOREPLACE Does not replace an existing program by the same name in the specified 
library. 


*REPLACE Replaces the existing program by moving it to the QRPLOBJ library. 


Generate listing 


Generates an output listing. 

The values allowed are: 
*NOLIST Does not generate a listing. 
*LIST Generates a listing. 


You must specify the following parameters: 
o Printer file name and library 


o Starting page number 


Create cross-reference listing 


Whether the listing is to contain a cross-reference list of variable and data item references. 
The values allowed are: 
*NOXREF Does not create cross-reference listing. 


*XREF Creates a cross-reference listing of references to variables, labels, or both. 


Create summary listing 


Whether the listing is to contain a list of program attributes. 
The values allowed are: 
*NOATR Does not create a summary listing section. 


*ATR Creates a summary listing section. 


User profile 


The values allowed are: 


*USER The user profile of the user running the program is used as a source of authority 
when this program runs. 


*ADOPT When the program runs, the object authority of both the program's owner and user 
are used. 


*OWNER The system uses the user profile of the owner of the program as a source of authority 
when this program runs. Programs called by this program adopt this authority. 


Use adopted authority 


Whether the system uses the program-adopted authority from the calling programs as a source of 
authority when this program is running. The user must be authorized to create programs with 
adopted authority for the *ADPAUT option to take effect. 


The values allowed are: 
*ADPAUT The system uses program-adopted authority from the calling program. 


*NOADPAUT The system does not use program-adopted authority from the calling program. 


Note: Authorization to create programs which can adopt authority is controlled by the 
QUSEADPAUT system value. For more information, refer to the description of this system value 


in the Work Mana ement book on the V5R1 Supplemental Manuals Web site. 


Constrain arrays 


The values allowed are: 


*SUBSCR Constrains arrays. This requests additional run-time checks to ensure that 
references to array elements are not outside the bounds of the declare statement. 
This option causes the resulting program to run slower. 


*NOSUBSCR_ Does not constrain arrays. The results of references to array elements outside the 
bounds of the declare statement are not defined. 


*UNCON Allows fully unconstrained arrays. This ensures that references to array elements 
outside the bounds of the declare statement act as if the array element actually 
exists. 


Note: This program attribute may be changed at run-time using the Override Program Attributes 
(OVRPGATR) MI instruction. 


Constrain strings 


The values allowed are: 


*SUBSTR Constrains strings. This requests additional run-time checks to ensure that 
references to character strings are not outside the bounds of the declare 
statement. This option causes the resulting program to run slower. 


*NOSUBSTR Does not constrain strings. The results of substring references outside the bounds 
of the declare statement are not defined. 


Note: You can change this program attribute at run-time using the Override Program Attributes 
(OVRPGATR) MI instruction. 


Initialize static storage 


Static storage is allocated the first time a program is called. It remains allocated until explicitly 
deallocated. 


The values allowed are: 


*CLRPSSA Initializes static storage. This code clears the program static storage area 
(PSSA) on entry using the Call External (CALLX) MI instruction. 


*NOCLRPSSA_ Does not initialize the PSSA. 


Initialize automatic storage 


Automatic storage is allocated each time a program runs and automatically deallocated when no 
longer needed. 


The values allowed are: 


*CLRPASA Initializes automatic storage. This code clears the program automatic storage 
area (PASA) on entry using the Call External (CALLX) MI instruction. 


*NOCLRPASA Does not initialize the PASA. 


Ignore decimal data errors 
Whether errors found in decimal data result in exceptions. 
The values allowed are: 
*NOIGNDEC Does not ignore decimal data errors. 
When you specify *NOIGNDEC, decimal values used in numeric operations are 
checked for valid decimal digits and sign codes. If the system finds an error, it 
signals an exception. 
*IGNDEC Ignores data decimal errors. 
When you specify *IGNDEC, decimal values used in numeric operations ensure 
they contain valid decimal digit and sign codes. However, the system treats 


digits that are not valid as zeros and signs that are not valid as positive signs. 
There is no exception signaled. 


This option applies to only a subset of the numeric operations you specify. 


Note: In all cases, the system signals decimal data errors if you use data pointers to address any of 
the instruction's operands. 


The following list contains the MI instructions this option affects: 


Operands 
MI Instruction |Supported Supported Notes 


a a a a 
[CMPNV- a. ee ee 


a You must specify operand 3 
(the numeric view to be used 
for operand 2) as a constant 
and no data-pointer-defined 
operands. 


[CVIDFFP | 


CVTNC Xx Xx You must specify operand 3 
(the numeric view to be used 
for operand 1) as a constant 
and no data-pointer-defined 
operands. 


CPYNV Xx x You must specify no 
a operands. 


ERE -—3=-— 

aa You must specify no 
data-pointer-defined operands. 

[EXTRMAG ~ [i - = = =| = | 


car CALE | | x | 
[s UBN | | x | 
When you specify *IGNDEC, the system may still signal the decimal data exception. That is, other 


M1 instructions and instruction combinations not listed above may signal the decimal data 
exception when the system finds decimal data that is bad. 


Ignore binary data size errors 
The values allowed are: 
*NOIGNBIN _ The system handles binary data size errors normally. When a binary size error 


occurs, an exception is signaled and the receiver contains the left-truncated 
result. 


*IGNBIN The system ignores binary data size errors. This is used when an overflow or 
underflow occurs on a computation and when a control MI instruction has a 
receiver that is a binary field. The receiver contains the left-truncated result. 


Support coincident operands 


The system overlaps coincident operands between the source and receiver operands in one or more 
program instructions. Coincident operands are operands that overlap physically, in storage. 


The values allowed are: 


*NOOVERLAP Does not support coincident operands. If you specify *NOOVERLAP, you 


guarantee that coincident operand overlap will not occur while running the 
instruction. Therefore, the system can use the receiver on an instruction as a 
work area during operations performed to produce the final result. Using the 
receiver as a work area does not use as much processor resource as would be 
required to move the final result from an internal work area to the receiver. 


*OVERLAP Supports coincident operands. If you specify “OVERLAP, the operands on an 


MI instruction may overlap. Therefore, the system cannot use the receiver on 
an instruction as a work area during operations that produce the final result. 
This can require more processor resource for running the instruction but it 
ensures valid results if an overlap occurs. 


The following is a list of instructions this option affects: 


Oo 


QO O 0. 0. °O. 0 © 0 "O "Oo Oo 0 O O Oo. O 0 Oo 0 © © 


Add logical character (ADDLC) 

Add numeric (ADDN) 

And (AND) 

Compute math function using one input value (CMF1) 
Concatenate (CAT) 

Convert character to numeric (CVTCN) 

Convert decimal form to floating-point (CVTDFFP) 
Convert external form to numeric value (CVTEFN) 
Convert floating-point to decimal form (CVTFPDF) 
Convert numeric to character (CVTNC) 

Copy bytes left adjusted with pad (CPYBLAP) 
Copy bytes right adjusted with pad (CPYBRAP) 
Divide (DIV) 

Divide with remainder (DIVREM) 

Exclusive or (XOR) 

Multiply (MULT) 

Or (OR) 

Remainder (REM) 

Scale (SCALE) 

Subtract logical character (SUBLC) 

Subtract numeric (SUBN) 

Trim length (TRIML) 


Allow duplicate declares 


The values allowed are: 


*NOD 


*DUP 


UP This does not allow a program object to be declared more than once. This requests 
that duplicate declare (DCL) statements be diagnosed as errors. 


This allows a program object to be declared more than once. This requests that 
program objects declared more than once be pooled and not be diagnosed as errors. 


Optimize 


The values allowed are: 


*OPT This optimizes the program. In most instances, this produces the smallest and best 
running program. Occasionally, the source program may signal a MCH2802 escape 
message during processing. If this occurs, you should not optimize the program. 


*NOOPT This does not optimize the program. This requests the normal level code 
optimization when you create the program. 


Target release 


The release of the operating system on which you intend to use the object being created. You can 
use the object on a system with the specified release or with any subsequent release of the operating 
system installed. 

The values allowed are: 


*CURRENT _ The object is to be used on the release of the operating system currently running 
on your system. 


*PRV The object is to be used on the previous release with modification level 0 of the 
operating system. 


target-release Specify the release in the format VxRxMx. 
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Error Messages 


Message ID Error Message Text 

CPD0078 D Value &3 for parameter not a valid name. 

CPF2143 E Cannot allocate object &1 in &2 type *&3. 

CPF2144 E Not authorized to &1 in &2 type *&3. 

CPF2146 E Owner of object &1 and object being replaced not the same. 

CPF2283 E Authorization list &1 does not exist. 

CPF223B D &1 in &2 type *&3 adopted authority from previous call levels was set to *NO. 
CPF223E E Authority check for use adopted authority attribute failed. 

CPF3CF1 E Error code parameter not valid. 


CPF3C35 E Value &3 for parameter &2 not a valid name. 


CPF3C5A E 
CPF3C5B E 
CPF3C5C E 
CPF3C5D E 
CPF3C5F E 
CPF3C50 E 


CPF3C56 E 
CPF3C60 E 
CPF3C61 E 
CPF3C62 E 
CPF3C63 E 
CPF3C64 E 
CPF3C90 E 
CPF6301 E 


CPF6303 E 
CPF6304 E 
CPF6306 E 
CPF6307 E 
CPF6308 E 
CPF6309 E 
CPF6455 E 
CPF6457 E 
CPF6551 E 


Number of option template entries is not valid. 

Option template entry is not valid. 

Source file name and library is not valid. 

Source file member is not valid. 

Internal Representation of Program (IRP) string length parameter is not valid. 


Program &1 not created. 


CPD0078 D Value &3 for parameter not a valid name. 

CPD3C50D ~—~Value &1 for the IRG string length parameter was not valid. 
CPD3C52 D ~—_ Number of option template entries is not valid. 

CPD3C53 D ~—— Option template entry is not valid. 

CPD3C54D Source file name and library is not valid. 

CPD3C55 D Source file member is not valid. 

CPD3C56 D Source file last changed date and time is not valid. 


Source file last changed date and time is not valid. 
Program name and library is not valid. 

Authority is not valid. 

Source file library specified. 

Source file member specified. 

Source file last changed date and time specified. 
Literal value cannot be changed. 


Intermediate representation of program (IRP) contains &1 errors. Probable compiler 
error. 


Message &1, &2 received while running create program command. 
Library &1 not found. 

Program &1 in library &2 already exists. 

Program template value at offset &1, bit &2, length &3 not valid. 
Not authorized to create program. 

Not authorized to library &1. 

Member &2 file &1 in library &3 not found. 

Cannot allocate library &1 for program insertion. 


Work space &2 cannot be extended. Probable compiler error. 


CPF6552 E 
CPF6553 E 
CPF6554 E 
CPF6555 E 


CPF6557 E 
CPF6560 E 
CPF6561 E 
CPF6563 E 
CPF6564 E 
CPF6565 E 
CPF9872 E 


Space &2 type &3 subtype &4 not PRM workspace. 
PRM permanent table resolution failed. Probable compiler error. 
Type of IST object &4 at offset &3 not valid. Probable PRM error. 


Addressability field type not valid for IST number &4 at offset &3. Probable PRM 
error. 


Error condition for IST &4 at &3 of IST space not valid. Probable PRM error. 
Operation code &5 in MI instruction &3 at offset &6 not found in QPRODT. 
Operand &4 in &3 at offset &5 in program template not valid. 

Program was too large to be created. 

Machine storage limit violation. 

User profile storage limit exceeded. 


Program or service program &1 in library &2 ended. Reason code &3. 


Program Attributes 


The QPRCRTPG API creates programs that have the following attributes: 


e An associated space of 480 bytes initialized to hexadecimal 00. You can use the QCLSPGAS API 


to store information in the program's associated space. 


e@ Observability. 
e A blank extended attribute. 


Program Syntax 


A program object consists of an instruction stream and an object definition table (ODT). The 
intermediate representation of a program defines both of these components. It consists of one or more 


statements: 


oT Declare Statement 


PEND ; —fe 


Instruction Statement 
Directive Statement 


Instruction statements define MI instructions placed in the instruction stream. Declare statements define 
program objects placed in the ODT. Directive statements: 


e Control the formatting of the output listing. 
e Define entry-point program objects. 
e Define symbolic breakpoints. 


e Specify the end of the program. 
The following sections explain how to define these statements. 


Note: In the diagrams below, names that begin with an uppercase letter identify values specified in another 
diagram. Names that begin with a lowercase letter identify values defined in the table below the diagram. 


Label 


The following diagram and table show the possible labels: 


name : 


Each name specified in the label generates a branch-point program object corresponding to the next MI 
instruction. 


[Constant Range Description 
[name 1 Any Label name for next instruction 


Declare Statement 


Declare statements define program data objects. All the declare statements in a program build the object 
definition table (ODT). 


You cannot specifically declare branch and entry-point program objects. However, you can declare 
branch-point program objects using labels. You can also declare entry-point program objects using the 
entry directive statement. 
The types of declare statements follow: 
e Scalar Data Object Declare Statement 
Pointer Data Object Declare Statement 
Space Pointer Machine Object Declare Statement 
Operand List Declare Statement 
Instruction Definition List Declare Statement 


Exception Description Declare Statement 


Space Object Declare Statement 


e Constant Object Declare Statement 


Scalar-Data-Object Declare Statement 


The following diagram and table show the scalar-data-object declare statement: 


P—DCL DD Object Name ——-—_____,_________» 
! Array Attripute- 4 Scalar Type 


Addressabilitys ¢Sc opel + Boundary4+ Position 


Array Element Offsett + Optimization + |nitial values - 


Only certain combinations of attributes are allowed based on the data object's addressability. The table 
below shows these combinations. 


Array 
Array Element Initial 
Address-ability | Attribu Offset Position |Boundary | Value 
xX xX 


te 
i eS SS 


AUTO 


1 
Il 
il 
“ 
+ 


- 
: 


DIR f xk fh xk TOK x 


Object Name 


The following diagram and table show the possible object names: 


»— name] —h 


[Constant [Range [Description 
[name 1 [Any [Program object name to be declared 


Array Attribute 


The following diagram and table show the possible array attributes: 


>— | integer ea ta 
( integer? ¢ integers | 


[Constant [Range Description 
integerl |1 to 16776 191 Dimension of the data object with an 
implied lower bound of 1. 
integer2 |-2 147 483 648 to Lower bound of the array. 
2 147 483 647 


integer3 |integer2 to 2 147 483 647 Upper bound of the array. The 
dimension (integer3 - integer2) cannot 


exceed 16 776 191. 


Example 


The following declare statements each define an array of 50 elements. The elements of ARRAY 1 are 
numbered 1 to 50. The elements of ARRAY2 are numbered 0 to 49. Each element of the array is a BIN(2) 
field. The addressability of the arrays is static. 


DCL DD ARRAY1(50) BIN(2); 
DCL DD ARRAY2(0:49) BIN(2); 


Scalar Type 


The following diagram and tables show the possible data types of scalar items: 


CHAR ( integert } 
BIN ¢ integer? } 


UNSGNDOA 
PKD integer3-———, 
Sa q _integert 


FLT ¢ integers } 


If you specify no value, the system uses BIN(2). 


[Keyword [Description 
[CHAR [Scalar type is a character string. 
[BIN [Scalar type is binary. 


UNSGND |Scalar type is unsigned binary. If you do not specify this value, the 
scalar type is signed binary. 


[PKD [Scalar type is packed decimal. 
[ZN D [Scalar type is zoned decimal. 
[FLT [Scalar type is floating-point. 


[Constant [Range [Description 


integer! |See description. |Length in bytes of the character data object. If the data 
object is an array, the range is 1 to 32 767. Otherwise, 
the range is 1 to 16 776 191. 


linteger2 [2 or 4 [Length in bytes of the binary data object. 
[integer3 fi to 31 [Total digits in the data object. 


integer4 0 to integer3 Number of digits to the right of the assumed decimal 
point in the data object. 
r [4or8 


fintegers [4or8 40 Precision in [Precision in bytes of the dataobject. = [Precision in bytes of the dataobject. = the data object. 


Addressability 


The following diagram and tables show the possible addressabilities: 


DEF { name? } 
oe 


BASPCO 
PARKA 


[Keyword [Description 
[STAT [Addressability type is direct static. 
[AUTO |Addressability type is direct automatic. 


pr Addressability type is defined. See Using Space Objects for more 


information. 


[DEF [Addressability type is direct on the previous space. 
[BAS [Addressability type is based. 
[* [Object does not have explicit basing object. 


Pore oe type is based on process communication object space 
pointer. 


[PARM [Addressability type is a parameter. 


[Constant [Range [Description = ss—‘“i—sS 
[namel [Any |Spaceobjectname ———ssss—‘—sS 
Jname2 [Any _[Scalar data object name or pointer data objectname 
[name3 [Any __[Pointer data object name or space pointer objectname 


If you specify no value, the system uses STAT. 


Scope 


Scope refers to the ability to export a variable so that other programs can access it. The following diagram 


and table show the possible scopes: 
POINT 
EAT 


[Keyword [Description 
[INT [Data object is not externally accessible 


EXT [Data object is externally accessible 


If you specify no value, the system uses INT. 


Boundary 


The following diagram and table show the possible boundaries: 


»— EDRY { integer] ) ——1+ 


[Constant [Range [Description 
linteger! [1 2, 4, 8, 16 [Data object boundary 


Position 


The following diagram and table show the possible positions: 


»— Pos [ integer! ) —— 


[Constant [Range [Description 
lintegerl [i to 16 776 191 [Data object position 


Example 


The following declare statements show how POS can be used along with DEF to access the same storage 
space in different ways: 


DCL DD DATETIME CHAR(12); 
DCL DD DATE CHAR(6) DEF (DATETIME) ; 
DCL DD TIME CHAR(6) DEF (DATETIME) POS(7); 


DATETIME represents a 12 character time and date stamp. The first 6 characters contain the date and the 
second 6 characters contain the time. 


Array Element Offset 


The following diagram and table show the possible array element offsets: 


»— AE ( integerd | ——} 


[Constant [Range [Description 
linteger! [1 to 32767 [Array element offset 


Example 
The following example shows AEO used in conjunction with DEF and POS: 


DCL DD X as 6); 
DCL DD LFT(4) BIN(2) DEF (X) AEO(4) POS(1); 
DCL DD RGT(4) BIN(2 


Both LFT and RGT redefine the storage declared by X. Because the size of each array element is smaller 
than the array element offset, there are 2-byte gaps between each array element: 


LFT (1) LFT (2) LFT (3) LFT (th 


RGT (1) RGT (2) RIGT (3) RGT (4) 


Optimization 


Optimization determines whether or not an item can be moved to a register and stored there over time. The 
following diagram shows the possible optimization: 


»— ABN ——‘ 


This value indicates that the data object contains an abnormal value. You cannot optimize the value for 
more than a single reference because the value may be changed in a manner that the QPRCRTPG API 
cannot detect. 


Initial Value 


The following diagram and table show each possible initial value: 


ee Ly integers i 


«(integer | (integer } string! 


[Constant [Range [Description 


integerl |1 to 16776 191 Position of elements in a character 
string 


lintegerl [-2 147 483 648 to 2 147 483 647 [Position of elements in an array 


integer2 |1 to 16776 191 Replication factor in a character string 
or array 

integer3 |Any Initial value for signed and unsigned 
binary data objects 

string] Initial value for character string data 
objects 

packed1 |Any Initial value for packed decimal data 
objects 

zoned1 |Any Initial value for zoned decimal data 
objects 

float1 Any Initial value for floating-point data 
objects 


Example 
The following declare statement declares and initializes a 10-element array: 


DCL DD IVv(10) BIN(2) STAT INIT((1)10,* (2) (2)11,*%* (4) (3)12,%* (7) (4) 13); 


There are four initial value elements. The following table describes this function: 


Initial Value Replication 
Element Result Position Factor Initial value 


[(1)10 [IV()= 10 [I (default) L fio 


*(2)(2)11 2 — 
V = 
IV(3)= 
*(4)(3)12 
IV (4) =12 
IV(5)=12 
IV (6) =12 


*(7)(4)13 


Pointer-Data-Object Declare Statement 


The following diagram and table show the pointer-data-object declare statement: 


— DCL Pointer Type Object Name ———____» 
mee Array Attribute 


Address ability Position Atray Element Offset 


Se 


Optimization Initial Value 


The system only allows certain combinations of attributes based on the data object's addressability. These 
combinations are listed as follows: 


Array 
Attribute 


Initial Value 
Attribute 


Address-ability 


pass | XC 
IBASPCO. |x ||... 
PARM | XP 


Pointer Type 


The following diagram and table show the possible pointer types: 


ETE 
INSPTR 
SPCPTR 
CTAPTR 
SYSPTR 


[Keyword Description 

PTR Pointer type is not specified. 
[INSPTR Pointer type is the instruction pointer. 
[SPCPTR Pointer type is the space pointer. 
[DTAPTR Pointer type is the data pointer. 
[SYSPTR Pointer type is the system pointer. 


If you specify an initial value, you must specify INSPTR, SPCPTR, DTAPTR or SYSPTR. 


Array Attribute 


The following diagram and table show the possible array attributes: 


PT. { is Goren ae 
( integers : integers) 


[Constant [Range [Description 
integer! |1 to 1 000 000 Dimension of the data object with an 
implied lower bound of 1. 
integer2 |-2 147 483 648 to Lower bound of the array. 
2 147 483 647 


integer3 |integer2 to 2 147 483 647 Upper bound of the array. The 
dimension (integer3 - integer2) should 


not exceed 1 000 000. 


Addressability 


The following diagram and tables show the possible addressabilities: 


STAT 
AUTO 


eal ( name } 


DEF (names) 
BAS (TL names —- \ 


BASPCO 
PAR 


[Keyword [Description 
[STAT [Addressability type is direct static. 
[AUTO [Addressability type is direct automatic. 


DIR Addressability type is defined. See Using Space Objects for more 
information. 


[DEF [Addressability type is defined. 
[BAS |Addressability type is based. 
[* [Object does not have explicit basing object. 


oa ao type is based on the process communication object space 
pointer. 


[PARM |Addressability type is parameter. 


[Constant [Range [Description 
Jnamel [Any [Space object name 
[name2 [Any [Scalar data object name or the pointer data object name 


name3 {Any _ |Pointer data object name or the space pointer machine object 
| | ie 


Position 


The following diagram and table show the possible positions: 


P— Pos [ integer! ) —— 


[Constant [Range [Description 
linteger! i to 16 776 191 [Data object position 


Array Element Offset Value 


The following diagram and table show the possible array element offset values: 


»— AE ( integerd | ——} 


[Constant [Range Description 
linteger! [i to 32 767 Array element offset 


Optimization 


The following diagram shows the possible optimizations: 
»>— ABN —— 


This value indicates that the data object contains an abnormal value. The system cannot optimize a value 
for more than a single reference because the value may be changed in a manner the QPRCRTPG API 
cannot find. 


Initial Value 


The following diagram shows each possible initial value: 


bp INIT! Instruction Pointer Initial Value i 
Space Pointer Initial Value 
Data Pointer Initial Value 
System Pointer Initial Value 


An initial value can only be specified if a pointer-type value other than PTR is specified. The syntax of the 
initial value is based on the pointer-type value that was used. 


Instruction Pointer Initial Value 


The following diagram and table show the possible initial value for the instruction pointer: 


»— name] — 


[Constant Range [Description 
[name | Any [Label name 


Example 


The following statement declares and initializes an instruction pointer: 


LABELI: 


DCL INSPTR INSTRUCTION_PTR INIT (LABELT) ; 


Space Pointer Initial Value 


The following diagram and table show the initial value for the space pointer: 


»— name] —h 


[Constant [Range [Description 
[name 1 [Any [Scalar data object name or pointer data object name 


Example 


The following statement declares and initializes a space pointer: 


DCL PTR ANY_POINTER; 
DCL SPCPTR SPACE_PTR INIT (ANY_POINTER) ; 


The pointer SPACE_PTR is initialized to point to the space location containing ANY_POINTER. It does 
not contain the value of ANY_POINTER. 


Data Pointer Initial Value 
The following diagram and table show the initial value for the data pointer: 


»—_— i a pear | Cl 
» PG! string? \ 
L intager1— 


[Constant [Range [Description = ss—‘—sS 
string! [32 bytes [Externaldataobjectname = 
[string2 [30 bytes [Program containing external data object = 
jintegerl 0 to. 255 [Subtypeofprogram 


Example 
The following statement declares and initializes a data pointer: 


DCL DTAPTR DVALUE INIT ("DBINARY",PGM("DPGM") ); 


The pointer DTAPTR refers to the externally defined program object DBINARY contained in program 
DPGM. 


System Pointer Initial Value 


The following diagram and tables show the initial value for the system pointer: 


— string] 
CTX ( string? } 
L , Integer +_] 


L » TYPE ( name a eee wal \ 
Integer 2 


[Constant [Range = —*([Description = s— 
string! [1 to30 bytes = [Systemobject 
[string2 [1 to30 bytes [Context where the system object is located 
lintegerl [0to255 = [Subtypeofthe context = 
[namel —‘[See table below. [Symbolic type of the system object 
linteger2 [0to255 [Subtype ofthe systemobject = 


The following system object types are supported: 


[Type =—S———s«d[Deseription eesses—S 
PGM [Program 
CTX [Context 
JQ Quete 
[SPC [Space 

PCS [Processcontrolspacesssssss—Ss 


Example 


The following statement declares and initializes a system pointer: 


DCL SYSPTR SYSTEM_PTR INIT ("MYPGM", CTX ("PGMLIB") , TYPE (PGM) ); 


The pointer SYSTEM_PTR refers to the *PGM object MYPGM in the PGMLIB library. 


Space-Pointer-Machine-Object Declare Statement 


The following diagram and table show the space-pointer-machine-object declare statement: 


— DCL MSPPTR Object Marne ——_» 


= INIT ¢ Space Pointer Initial Value = 


, 
OPT f integer } 


[Constant [Range Description 
linteger! (0 to 255 |Optimization priority value, where 255 is the highest priority 


The iSeries system provides two types of pointers that can access data: 
e Space Pointers (SPCPTR) 
e Machine Space Pointers (MSPPTR) 


The MSPPTR has the following restrictions: 
oO. It cannot be passed as a parameter 
o It cannot be part of a structure (SPC) 
o It cannot be based (BAS(on_some_pointer)) pointer 
oO Itis logically only automatic (AUTO) in storage scope 
Because the MSPPTR has the above restrictions, the translator often assigns the MSPPTR to a hardware 


register for the life of the entire program unit. What this means is that loads may be eliminated from the 
generated code. 


Operand-List Declare Statement 


The following diagram and tables show the operand-list declare statement: 


P— DCL OL Object Name - (-namel7) —t 


t 


Eo ARG 1—* 
FARM INT | Ltn { integerd \ 
EXT 


[Keyword =———s [Description ess 
ARG [Defines the argumentlist 
[PARM  —s|Definestthe parameter list 
INT [Aninternal parameter list = 


EXT An external parameter list 


[Constant [Range [Description 
namel Any Scalar data object or a pointer data object name. Up to 255 
names can be specified. 


integer! |0 to 255 |Minimum number of elements that the list can contain. This 
implicitly defines a variable-length operand list. If you do not 


specify the operand list, the system defines a fixed-length 
operand list. Up to 255 names can be specified. 


Example 


The following statements declare both argument and parameter operand lists along with the associated 
argument and parameter data objects: 


DCL DD ARG1 BIN(2); 

DCL DD ARG2 CHAR(3); 

DCL OL ARGUMENT_LIST (ARG1, ARG2) ARG; 

DCL DD PARM1 BIN(2) PARM; 

DCL DD PARM2 CHAR(3) PARM; 

DCL OL PARAMETER_LIST (PARM1, PARM2) PARM EXT; 


A parameter operand list that refers to the data objects has parameter (PARM) addressability. 


Instruction-Definition-List Declare Statement 


The following diagram and table show the instruction-definition-list declare statement: 


P— DCLIDL Object Name - (- named -}—» 


[Constant Range |Description 
[name 1 Any Label name. Up to 255 names can be specified. 


Example 


The following statements declare and use an instruction definition list: 


LABEL1: 


DCL IDL INSTRUCTION_LIST (LABEL1, LABEL2, LABEL3) ; 


LABEL2: 
B INSTRUCTION_LIST(3); /* Branch to LABEL3 */ 


LABEL3: 


Exception-Description Declare Statement 


The following diagram and tables show the exception-description declare statement: 


h— DCL EXCM Object Marne t— 


h— ExXciD f— integen—— } INT 
sa | £ BP 


ExT 


[tah 
IVIL 
KP 
Fist 
DFR 


C¥ f string } 


[Keyword Description 


INT Exception handler type is the internal entry point. 
[BP Exception handler type is the internal branch point. 


[EXT Exception handler type is the external entry point. 


IGN Exception handling action ignores any exceptions and continues 
processing. 


IMD Exception handling action passes control to the specified exception 
handler. This is the default. 
Exception handling action is to continue to search for another exception 
description to handle the exception. 
Exception handling action continues to search for an exception 
description by signaling the exception again to the previous call. 


DFR Exception handling action postpones handling and saves exception data 
for later exception handling. 


[Constant [Range [Description 
linteger! [0 to 65535 [Exception identifier 
and the name of the system pointer for the external 


name 1 Any Name of the label for branch point exception handlers, 
exception handlers 


name of the entry point for the internal exception handlers, 
[string] [1 to 32 bytes [Compare value 


Space-Object Declare Statement 


The following diagram and tables show the space-object declare statement: 


h— DCL SPC Object ey ee ay 
BASPCO 


[Keyword [Description 
[BAS [Addressability type is based. 
[* [Object does not have explicit basing object. 


BASPCO |Addressability type is based on process communication object space 
pointer. 

[Constant [Range [Description 

[name 1 [Any [Basing pointer name for the space 


For information on using space objects, refer to Using Space Objects. 


Constant-Object Declare Statement 


The following diagram and tables show the constant-object declare statement: 


P— DCL CON Object Name 


CHAR (integer 5 
BIN { integer2 } 


LL UN SND 


aah ( integers IL, Gael. j 
AND _ ntegerd 


FLT ( integers } 
P— INIT { Data Object Initial Yalue }—— . — 


[Keyword —s [Description = sss—i‘“—s~—~—S 
[CHAR ——~—~*s«*Y Sci typecisccharacte' string. = — 
BIN [Scalartypeisbinary. ss 
[UNSGND Ss [Scalartypeisunsignedbinary, = 
[PKD = —“‘«~ti‘s™*C‘*W Sailr type is packed decimal. = — 
ZND [Scalartypeiszoneddecimal. = ssss— 
FLT [Scalartypeis floating-point. = 


If you do not specify a scalar type, the system uses BIN(2). 


Instruction Statement 


An instruction statement defines an MI instruction. The instruction stream used to create the program is 
made up of all the instruction statements in the intermediate representation of the program. 


»—_— Te ee 
Fall j 


[Constant [Range Description 


namel See description. |Opcode for this instruction, as defined in the iSeries 
Machine Interface Instructions. 


name2 S, R, B, I This is the form of the instruction. 
Short 
Round 
Branch 
Indicator 


For the semantic meanings and the syntax restrictions (number and types of operands, optional forms, and 
so on) for individual MI instructions, see the iSeries Machine Interface Instructions. 


Bn BD HA 


~ 


Following the abbreviated instruction name, you can specify the optional forms of certain MI instructions 
using a string of characters enclosed in parentheses. The following is an example of some of the various 
combinations possible for a single MI instruction, ADD NUMERIC: 


ADDN A,B,C; Add numeric (A=B+C) 

ADDN (S) A,B; Add numeric short (A=A+B) 

ADDN(SR) A,B; Add numeric short and round (A=A+B) 
ADDN(SB) A,B/POS(X),NEG(Y); Add numeric short and branch (A=A+B, 


branch to X if A>O, branch to Y if A<0) 
ADDN(RI) A,B,C/POS(I),NEG(J); Add numeric round and indicator (A=B+C; 
IT='on' if A>O; j='on' if A<O ) 


Also note that the order of characters in the optional form string is not significant. Thus, all of the following 
instructions are both valid and equivalent: 


ADDN (SRB) A,B/POS (X) ; Add numeric short, round and branch 
ADDN (SBR) A,B/POS (X) ; Add numeric short, round and branch 
ADDN (RSB)A,B/POS (X) ; Add numeric short, round and branch 


Operand 


The following diagram and table show the possible operands: 


Variable —Operand 
Integer 

string 

packed 

Zoned] 

float 


Relative Branch Target 


[Constant [Range [Description = ss—s—SsS 
fintegerl [Any Numeric binary scalar operand 

string [Any [Characterscalaroperand sss—S 
[packed [Any Numeric packed decimal scalar operand 

Jzonedl1 = [Any Numeric zoned decimal scalar operand 

float! [Any —_ [Numeric floating-point scalar operand (4 or 8 bytes) 
a Null operand 


Variable Operand 


The following diagram and table show the possible variable operands: 


ca eer | name Lista 
name? ( Index \ 


: Index? 
L 2L , |Indexd 


[Constant [Range [Description 
[name I [Any [Data object name to be used as a primary operand. 
[name2 [Any [Pointer data object to be used as the basing pointer. 


Index1 __|See description. |Subscript or substring start position. The range for array 
subscripts is between the lower bound of the array and 
the upper bound of the array. The range for substrings is 
between | and 16 776 191. 


[Index2 [1 to 32 767 [Length of the substring. 
[Index3 [0 to 32 767 [Length of the substring (zero allowed). 


Relative Branch Target 


The following diagram and table show the possible relative branch targets: 


cade +7 Intecqe rt] — 


[Constant [Range [Description 
integer! |1 to 4095 |Branch target instruction number relative to the current 
instruction. You must label the target (named or null label). 


Note: You cannot use blanks between either the '' 


=t+ 


"symbol set and integer] or the ' 


"symbol set and integer1. However, a blank must precede the symbol sets. 


Example 


The following instructions illustrate the use of relative branch targets: 


CPYNV X,0; 

CMPBLA(B) A, '1'/EQ( =+2); 

CPYNV X,1; 

CPYNV Y,X; /* Destination of relative branch */ 


Note: A null label is placed in the destination instruction of the relative branch. 


Target 
The following diagram and table show the possible targets: 
—— name { name? \——-} 
( Index } 


Relative Branch Target 


[Constant [Range [Description 


See keyword table. |Keyword for branch or indicator forms. You can use 
an N before keywords to negate the condition except 
for IGN and DFR. See "Resultant Conditions", under 
each MI instruction for the valid values. 


name 1 


name2 {Any Label name, instruction pointer name, or instruction 
definition list name for the branch form. The name of 
character variable is for the indicator form. 


Indexl {1 to 255 Instruction definition list index. You can only specify 
this value when name2 is the name of an instruction 
definition list. 


The following table shows the branch and indicator keywords: 


[Keyword Description 


Group 1 
HI MXD NOR POS TR ZC High Mixed Normalized Positive Truncated 
record Zero and carry 


Complete record Denormalized Exception 
ignored Low Negative Not-zero and no carry 
Receiver overrun 


AUTH DER DQ EQ INF SE 


Authorized Exception postponed Dequeued 
SGN ZER ZNTC Equal Infinity Source all used Signaled Zero 
Zero and no carry 


[Group 4 

EC NAN NTZC UNEQ UNOR __|Escape code encountered Not a number (NaN) 
Not-zero and carry Unequal Unordered 

By adding N to the beginning of the appropriate keyword you can form a not condition. For example, the 

code for "not equal” is NEQ. 


All conditions coded on a particular instruction must be mutually exclusive. All conditions within a group 
are equivalent, and therefore, only one may be specified. For example, POS (positive) and HI (high) cannot 
be coded on the same instruction. 


The not form of a condition is satisfied by any condition from another group. For example, NEQ (not equal) 
is satisfied by HI (high), LO dow), or UNOR (unordered). Therefore, you cannot specify NEQ with any of 
the other three. However, you can use NEQ and EQ (or any other keyword in group 3) together because 
they are mutually exclusive. 


Index 


The following diagram and table show the possible indexes: 


ee name 
Integer 


[Constant [Range [Description 
[name 1 [See description below. [Binary variable to use as the index 
lintegerl [See description below. [Integer value to use as the index 


An index is a numeric value that qualifies an array or substring reference. The context in which the index is 
used determines the range. For more information, refer to the preceding tables. 


Directive Statements 


The directive statements are as follows: 
e Title Directive Statement 
e Space Directive Statement 
Eject Directive Statement 


Break Directive Statement 


e 

e 

e Entry Directive Statement 
e Reset Directive Statement 
© 


Program End Directive Statement 


Title Directive Statement 


The title directive statement causes a heading to appear on the listings. Only one title directive statement 
may be specified in a program. The following diagram and table show the title directive statement: 


h»— TITLE string 1— ; —-} 


[Constant [Range [Description 
[string] [Any [Text of the title 


Space Directive Statement 


The space directive statement causes a blank line to appear in the listing. The following diagram and table 
show the space directive statement: 


ee SPACE Thies /_——> 
integer 


[Constant [Range [Description | 


linteger! [Any [Number of lines to skip 


Eject Directive Statement 


The eject directive statement causes the next line to appear on a new page. The following diagram shows 
the eject directive statement: 


e— EJECT — ;——-+ 


Break Directive Statement 


The break directive statement allows symbolic breakpoints to be defined. The following diagram and table 
show the break directive statement: 


p>— BRE string] — ;—h 


[Constant [Range [Description 
[string 1 [Any [Breakpoint name 


Entry Directive Statement 


The following diagram and tables show the entry directive statement: 


i>— Se 
name 


BRE. string 


[Keyword|Description eee 
[INT [Internalentry point. 
[EXT  ‘[Externalentrypoint. ss sss—s—sSSSCSs 
[BRK —_ [Symbolic breakpoint is associated with the entry point. 


7 Entry point defined has no name or is associated with the next MI 
instruction. 


[Constant [Range [Description = ss—<—sS 
[namel = [Any —*'[Entry pointname beingdefined == 
[name2 ss [Any —_—s*[Parameter listname for this entry point = 
string! [I-10 bytes. [Breakpointname sss 


The default scope is internal (INT). 


The entry statement defines entry point program objects. The next instruction number is associated with this 
entry point. The entry statement is to be the definition point for this object, so the ODT number assigned to 
this object is the next available ODT number. 


Reset Directive Statement 


The following diagram shows the reset directive statement: 


»— RESET name ; ——t 


The specified name is a previously declared space object. The reset statement causes subsequent data object 
declarations containing the DIR attribute to use the specified space object. The system maintains next byte 
counts for each space object; these counts are not affected by the reset statement. For more information, see 
Using Space Objects. 


Program End Directive Statement 


The following diagram shows the program end directive statement: 
>— PENL— | —-+ 


This must be the last statement in the program. To ensure comments and strings end before processing the 
PEND statement, use the following statement: 


JEN /HU/HN/*MK/ | PEND; 35 


Coding Techniques 


This section contains additional information for coding the intermediate representation of a program. 


Using Declare Statements 


Use the following guidelines when using declare statements: 
e A declare statement for data objects defined on another data object must occur after the declare 
statement for the data object on which it is defined. 


Example: The following sets of declare statements are valid: 


DCL DD A CHAR(5); 
DCL DD B CHAR(1) DEF (A); 


DCL DD A CHAR(5); 

DCL DD X BIN(2); 

DCL PTR Pl AUTO; 

DCL DD B CHAR(1) DEF (A); 


Example: The following declare statements are not valid because B is defined on A but is declared 
before A: 


DCL DD B CHAR(1) DEF (A); 
DCL DD A CHAR(5); 


This restriction also applies when there is a chain of dependencies. 


Example: In the figure below, B is defined on A and C is defined on B: 


DCL DD A CHAR(5); 
DCL DD B CHAR(3) DEF (A) 
DCL DD C CHAR(1) DEF (B) 


If any object in a chain of definitions, as shown in the previous examples, has an initial value 
specified, then the following restrictions apply: 
o No object in that chain can have the BAS (based) addressability attribute. 


oO The highest level data object in the chain must be either static or automatic. 


oOo When you initialize the same area twice, the system uses the last value. 


Example: The following declare statements are valid because: 
o The BAS addressability attribute is not used. 
o Data object A (implicitly) has the static addressability attribute. 


DCL DD A CHAR(5); 
DCL DD B CHAR(3) DEF (A) INIT(C'YES'); 
DCL DD C CHAR(1) DEF (B); 


e All declare statements for the objects that make up the elements of an operand list must precede the 
declare statement for the operand list. 


e@ When a declare statement for an exception description refers to a system pointer, the declare 
statement for the system pointer must precede the DCL for the exception description. 


Using Space Objects 


Space objects, when used in conjunction with program objects declared with the DIR attribute, provide a 
convenient way of declaring structures. 


Note: Space objects, as used here, do not refer to OS/400 space objects. 


When you declare a space object, a scalar data object with a scalar type of CHAR(32767) is created. This 
object contains the structure to be defined. Associated with this object is a "next byte” count. This value is 
initially 1 and represents the position where the next structure element will be placed. 


Example: Simple Space Objects 


After you declare a space object, you can declare one or more scalar or pointer data objects with an 
addressability attribute of DIR. As a result, the system automatically declares each object with the DEF and 
POS attributes. The name associated with the DEF attribute is the most recently declared space object. The 
value associated with the POS attribute is the space object's next byte count. After you declare the object, 
the system sets the next byte count associated with the space object to the next available position within the 
structure. 


The group of declare statements on the left is equivalent to the group on the right: 


DCL SPC X BAS(PTR); DCL DD X CHAR(32767) BAS (PTR); 
DCL DD A CHAR(2) DIR; DCL DD A CHAR(2) DEF(X) POS(1); 
DCL DD B ZND(5,2) DIR; DCL DD B ZND(5,2) DEF (X) POS(3); 
DCL DD C FLT(4) DIR; DCL DD C FLT(4) DEF (X) POS(8); 


Example: Explicit Position Values 


Data objects declared with DIR may also have an explicit POS value. The object is defined on the 
appropriate space object and uses the specified POS value. However, the next byte count is changed only if 
the POS value causes the count to increase. 


The group of declare statements on the left is equivalent to the group on the right: 


DCL SPC X BAS(PTR); DCL DD X CHAR(32767) BAS (PTR); 

DCL DD A CHAR(4) DIR; DCL DD A CHAR(4) DEF (X) POS(1); 
DCL DD B CHAR(4) POS(20) DIR; DCL DD B CHAR(4) DEF (X) POS(20); 
DCL DD C CHAR(4) DIR; DCL DD C CHAR(4) DEF (X) POS(24); 
DCL DD D CHAR(4) POS(10) DIR; DCL DD D CHAR(4) DEF (X) POS(10); 
DCL DD E CHAR(4) DIR; DCL DD E CHAR(4) DEF (X) POS(28); 


Example: Explicit Boundary Alignment 


When you declare objects with an explicit boundary other than 1, the object is positioned on the next 
available byte with that boundary. The position of any data object with the direct attribute is the next 
available byte in the space if no boundary or position is specified. The position of any pointer object with 
the direct attribute is the next available byte in the space if no position is specified. Space objects are 
assumed to begin on a 16-byte boundary. You must ensure this condition exists at run-time. 


The group of declare statements on the left is equivalent to the group on the right: 


DCL SPC X BAS(PTR); DCL DD X CHAR(32767) BAS (PTR); 
DCL DD A CHAR(1) DIR; DCL DD A CHAR(1) DEF (X) POS(1); 
DCL DD B FLT(4) DIR; BDRY(4); DCL DD B FLT(4) DEF(X) POS(5); 
DCL PTR C DIR; POS(17); DCL PTR C DEF (X) POS(17); 


Example: Reset Directive Statement 


You can use the reset directive statement to change the name of the space object to be used by subsequent 
declare statements. 


The group of declare statements on the left is equivalent to the group on the right: 


DCL SPCPTR PTR1; DCL SPCPTR PTRI1; 

DCL SPCPTR PTR2; DCL SPCPTR PTR2; 

DCL SPC X BAS(PTR1); DCL DD X CHAR(32767) BAS(PTR1); 
DCL DD A CHAR(2) DIR; DCL DD A CHAR(2) DEF (X) POS(1); 
DCL DD B ZND(5,2) DIR; DCL DD B ZND(5,2) DEF (X) POS(3); 
DCL SPC Y BAS(PTR2); DCL DD Y CHAR(32767) BAS(PTR2); 
DCL DD C CHAR(5) DIR; DCL DD C CHAR(5) DEF(Y) POS(1); 
DCL DD D CHAR(7) DIR; DCL DD D CHAR(7) DEF (Y) POS(6); 
RESET X; 

DCL DD E CHAR(3) DIR; DCL DD E CHAR(3) DEF (X) POS(8); 
Constants 


This section describes the syntax of constant values. 


Integer 


Integers define signed and unsigned binary scalar data values. The two forms of integers are decimal and 
hexadecimal. The decimal form is a sequence of digits optionally preceded by a sign. The hexadecimal 
form is a string of hexadecimal digits delimited with apostrophes and preceded by an H. Neither form may 
exceed the 4-byte limit on binary numbers. When the value of the integer is between -4095 and +8191, the 
QPRCRTPG API converts the integer to an immediate operand where it can. 


Example 


+123 
-1 
54788 


H'OFOD' 
H'0123' 
H'5E2D1AB4' 


String 


Strings define scalar character string data values. The three types of string constants are character form, 
hexadecimal form, and Hollerith form. 


The character form is a delimited string optionally preceded by a C. Apostrophes or double quotation marks 
may be used for this form. The hexadecimal form is a delimited string of hexadecimal digits preceded by an 
X. The Hollerith form is a string of bytes preceded by the count of the number of bytes in the string. The 
syntax is: 


< count | string > 


The count in the preceding syntax is the number of characters in the string. The QPRCRTPG API ensures 
that the string contains the right number of characters by checking for the 


> 


character. No blanks are allowed between 


and 


unless they are part of the string. The QPRCRTPG API simply flags the constant as in error if the right 
corner bracket does not appear in the correct position. 


Example 


The following groups of strings are equivalent: 


"ABCDE' 
C'ABCDE' 

Xt Clezescacs” 
<5 | ABCDE> 


'TR! "ST! 

TE? Sach 
X'E3C57DE2E3' 
<5|TE'ST> 


'/x*' 
X'615C' 
<2|/*> 


Packed 


Packed constants define packed decimal scalar data values. Packed constants are a string of decimal digits 
delimited with apostrophes. They can have an embedded decimal point and can be preceded by a sign. P 
must precede the delimited string. Packed constants have a maximum of 31 significant digits. 


Note: You must specify at least one numeric digit. 


Example 


P'+123.456' 

Pa 

PY 
P'-123.345345345345' 
P'+.Q00000000000001' 


Zoned 


Zoned constants define zoned decimal scalar data values. The external representation of zoned constants is 
the same as that for packed constants except that the preceding character is a Z. 


Note: You must specify at least one numeric digit. 


Example 


Z'4+123.456' 

Z'i1' 

Z'-1' 
Z'-123.345345345345' 
Z'+.00000000000001' 


Floating-Point Constants 


Floating-point constants define floating-point scalar data values. You must specify whether the constant is a 
4-byte (short floating-point) or an 8-byte (long floating-point) value. 


There are two ways to represent floating-point values. First, you can specify floating-point constants as a 
delimited string of decimal digits possibly with an embedded decimal point and optionally preceded by a 
sign. An F for short floating-point values or an E for long floating-point values must precede the delimited 
string. An E in the string determines the start of the base 10 exponent. You specify the exponent as signed. 


Second, you can specify floating-point constants as a string of hexadecimal digits. The delimited string 
must be preceded by an XF for short floating-point values or an XE for long floating-point values. 


Note: You must specify at least one numeric digit. 


Example 

Short Floating-Point Long Floating-Point 
Values Values 

F'o! E'O' 

F'+12!' Beith 

F'-12.21' E'-12.21' 

F'12.34E2' B'12.34E2' 
F'+3.2345678E-02' E'+3.2345678E-02' 
XF'449A4000' XE'46CE6F37FFBE8722'! 
XF'40490FD0' XE'400921F9F0O1B866E' 


Several special values are allowed: 


Short Floating-Point Long Floating-Point 


Values Values 

F'MNAN' E'MNAN' Masked Not A Number 
F'UNAN' E'UNAN' Unmasked Not A Number 
F'+INF'! E'+INF'! Plus Infinity 

F'-INF' E'-INF' Minus Infinity 


Note: You must use floating-point constants to initialize floating-point data objects. 


Name 


Names specified in the intermediate representation of a program are a sequence of characters of up to 48 
characters in length. You cannot use the following characters as the first character of the name: 


blank /,; ():<+'%-0123456789 


You cannot use the following characters in subsequent characters of the name: 


blank /,; ():<+'% 


Example 


- NAME 

NAME 

THIS_IS_A_ NAME 
THIS_IS_A NAME 2 
&NAME 

! NAME 

2?NAME 

-0001 


Note: Symbols that begin with a period (.) are not inserted into the program's symbol table and may not be 
referred to by the OS/400 debug function. 


Comments 


Comments, in the intermediate representation of a program, may appear anywhere in the text. Comments 
are treated as blanks so they are significant in finding tokens. Comments are a string of characters starting 
with 


/ * 
and ending with 
nf 


. If acomment occurs immediately following a semicolon, it prints as a separate line (or a multiple line as 
required) on the listing. If a comment is embedded in a statement, then it appears as a part of that statement, 
such as a remark. 


Example 


The following statements are equivalent: 


CPYBLA A,B; 
CPYBLA A, /* C-> */ B; 
CPYBLA A,B; /* B is based on C */ 


Blanks 


You can use strings of blanks of any length in the intermediate representation of a program. Blanks act as 
delimiters in finding tokens and in some places are necessary as in separating the opcode and operand in an 
instruction statement. 


Example 


The following statements are equivalent: 


ADDN A,B,C; 
ADDN A ; B , C r 


API Introduced: V1R3 
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End Preprocessor (QbnEndPreProcessor) API 


Required Parameter Group: 


Qualified input source filename Input Char(20) 
Input source member name Input Char(10) 
Qualified output source file name Input Char(20) 
Output source member name Input Char(10) 
Qualified exit program name Input Char(20) 
Exit program data Input Char(*) 

Length of exit program data Input Binary(4) 
Error code V/O Char(*) 


1 
2 
3 
4 
5 
6 
7 
8 


Service Program: QBNPREPR 
Default Public Authority: *USE 


Threadsafe: No 


The End Preprocessor (QbnEndPreProcessor) API must be called by every preprocessor after the output 
source file and preprocessor information is created. It records the fact that a preprocessor was called and 
may be used to pass information used during module creation. This information can be classified as 
follows: 


e Associated space data 
e Extended attribute data 
e Preprocessor level data 
e Name of an exit program to call at ILE program creation time 
The End Preprocessor API then moves the above information in the output source file member where it is 


used at module creation time. The initial preprocessor may get input from inline data, but all subsequent 
preprocessors must get their input from the output file member of the previous preprocessor. 


The output source file created by a previous preprocessor must not be changed. If the output file has been 
changed, module creation fails. 


Authorizations and Locks 


Input Source File Authority 
*READ and *OBJOPR 

Input Source Library Authority 
*EXECUTE 

Output Source File Authority 
*CHANGE and *OBJOPR 

Output Source File Member Lock 
*EXCL 


Output Source Library Authority 
*EXECUTE 


Required Parameter Group 


Qualified input source file name 
INPUT; CHAR(20) 
The qualified name of the input source file to the preprocessor. The first 10 characters contain the 
input source file name, which is left-justified and padded with blanks. The second 10 characters 


contain the input source file library, which is left-justified and padded with blanks. The input 
source file name can be specified with the following special value: 


*INLINE The input source data is specified as an inline data file. 


Input source member name 
INPUT; CHAR(10) 
The name of the member within the input source file, which is left-justified and padded with 
blanks. This parameter is ignored if the qualified input source file name parameter is *INLINE. 
Qualified output source file name 
INPUT; CHAR(20) 
The qualified name of the output source file to the preprocessor. The first 10 characters contain the 


output source file name. The file is left-justified and padded with blanks. The second 10 characters 
contain the output source file library name. The file is left-justified and padded with blanks. 


Output source member name 
INPUT; CHAR(10) 
The name of the member within the output source file. The file is left-justified and padded with 
blanks. 

Qualified exit program name 
INPUT; CHAR(20) 
The qualified name of the exit program to be called during module creation. The first 10 characters 
contain the exit program name, which is left-justified and padded with blanks. The second 10 


characters contain the exit program library where the exit program is located, which is left-justified 
and padded with blanks. You can use this special value for the exit program name: 


*NONE This indicates that there is no exit program. 


You can use this special value for the exit program library: 


*LIBL The library list. 


The exit program is passed five parameters when called. The first two parameters are the exit 
program data and the exit program data length. The third parameter is reserved CHAR(10). The 
fourth and fifth parameters are both reserved BINARY (4). 


The exit program data being used in this API is defined by the user. 
Exit program data 
INPUT; CHAR(*) 
Data that is stored with the output source file member. When module creation calls the exit 


program, a copy of the data is passed. The format of this data is specified by the preprocessor. This 
value is ignored if *NONE is specified for the qualified exit program name parameter. 


Length of exit program data 
INPUT; BINARY(4) 
The length of the data contained in the exit program data parameter. This value is ignored if 
*NONE is specified for the qualified exit program name parameter. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 

CPF2207 E Not authorized to use object &1 in library &3 type *&2. 
CPF24B4 E Severe error while addressing parameter list. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF5CAO E Input source file name &1 is not valid. 

CPF5CAI1 E Exit program name &1 is not valid. 

CPF5CEA E Library value &1 is not valid. 

CPF5CA4 E Error occurred while addressing API Parameter. 

CPF5D20 E Not able to open source file member &3. 

CPF5D21 E Not able to open source file member &3. 

CPF5D22 E Not able to locate internal data. 

CPF5D23 E Source file member has been changed. 

CPF5D24 E Unexpected error occurred during preprocessor processing. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V3R1 
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Execute Command (QCMDEXC) API 


Required Parameter Group: 


1 Command string Char(*) 
2 Length of command string Packed (15,5) 


Optional Parameter: 


3 IGC process control INPUT Char(3) 


Default Public Authority: *USE 


Threadsafe: Yes. See Usage Notes for command considerations. 


The Execute Command (QCMDEXC) API runs a single command. It is used to run a command from 
within a high-level language (HLL) program or from within a CL program where it is not known at compile 
time what command is to be run or what parameters are to be used. 


QCMDEXC is called from within your HLL program and the command it runs is passed to it as a 
parameter on the CALL command. 


After the command runs, control returns to your HLL program. 


Notes: 


1. Command strings in System/38 syntax can use the QCACHECK API. The QCACHECK API 
accepts the same parameters as QCMDEXC. 


2. The Process Commands (QCAPCMD) API also provides similar functions. 


Authorities and Locks 


Any Command 
*USE 


Required Parameter Group 


Command string 
INPUT;CHAR(*) 
The command you want to run entered as a character string. If the command contains blanks, it 


must be enclosed in apostrophes. The maximum length of the character string is 32,702 characters; 
delimiters (the apostrophes enclosing the string) are not counted as part of the string. 


Length of command string 


INPUT;PACKED(15,5) 


The maximum length being passed. If the command string is passed as a quoted string, the 
command length is exactly the length of the quoted string. If the command string is passed in a 
variable, the command length is the length of the variable. It is not necessary to reduce the 
command length to the actual length of the command string in the variable, although it is 
permissible to do so. 


Optional Parameter Group 
IGC process control 
INPUT:CHAR(3) 


The IGC process control instructs the system to accept double-byte data. The only value supported 
is IGC. ICG must be entered using all uppercase letters. 


Usage Notes 


While this API is threadsafe, it should not be used to run a command that is not threadsafe in a job that has 
multiple threads. Use the Display Command (DSPCMD) command to determine whether a command is 
threadsafe. 


Error Messages 


Message ID Error Message Text 

CPFO005 E Returned command string exceeds variable provided length 

CPFO006 E — Errors occurred in command. 

CPF3C90 E Literal value cannot be changed. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


xxxnnnnE Any escape message issued by any command may be returned. The messages listed 
previously are those issued by this API. Once the API has called the command analyzer, 
any message issued as an escape message may appear. 


API in existance prior to V1R3 
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Get Export (QleGetExp) API 


Omissible Parameter Group: 


Activation mark Binary(4) 
Export number Binary(4) 
Export name length Binary(4) 
Export name Char(*) 
Exported item PTR(OPN) 
Type of export item Binary(4) 
Error code Char(*) 


Returned Value: 


Exported item PTR(OPN) 


Service Program: QLEAWI 
Default Public Authority: *USE 


Threadsafe: Yes 


The Get Export (QleGetExp) API allows the caller to resolve a pointer to an export (either data or 
procedure) either by name or export number. The pointer is materialized for the specified activation. If the 
activation mark given is zero, then all activations in the activation group are searched (no guaranteed search 
order). 


Omissible Parameter Group 


Activation mark 
INPUT; BINARY(4) 


The activation containing the export. If this parameter is omitted, then it is treated as if a 0 was 
specified. This parameter may not be omitted if the search is done by export number. 


The following special value is supported for this parameter: 


0 All of the activations in the caller's activation group are searched. If more than one activation 
contains the specified export, it is undefined as to which of those activations the export is 
taken from. 


Export number 
INPUT; BINARY(4) 
Materialize the nth exported identifier in the service program. The order is defined by the binding 


service language with the first exported identifier being 1. If this parameter is omitted, then it is 
treated as if a O was specified. 


The following special value is supported for this parameter: 


0 Materialize the item named in the export name parameter. 


Export name length 
INPUT; BINARY(4) 


The length of the export name. If this parameter is omitted, then it is treated as if a 0 was specified. 
This parameter is ignored if the export number parameter is not zero. 


The following special value is supported for this parameter: 


O The export name is a null-terminated string. 


Export name 
INPUT; CHAR(*) 
A string containing the name of the exported identifier. The name is matched exactly, without 


CCSID conversion or folding to uppercase. This parameter is ignored if the export number 
parameter is not zero. The export name cannot be omitted if the export number is omitted. 


Exported item 
OUTPUT; PTR(OPN) 


The procedure pointer or space pointer to the exported item. If the identifier could not be exported, 
this value is null. 


Type of export item 
OUTPUT; BINARY(4) 


The type of the exported item. The possible types follow: 
O Export was not found 
I Export is a procedure 
2 Export is data 


3 Export not accessible 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 
Pointer to exported item 
OUTPUT; PTR(OPN) 


This API returns the value for the pointer to the exported item parameter. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1ID E Length specified in parameter &1 not valid. 

CPF3CIE E Required parameter &1 omitted. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
MCH4421 E At least one field in the allocation strategy is not valid. 


MCH4422 E &1 cannot be called in the default activation group. 


API Introduced: V3R6 
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List ILE Program Information (QBNLPGMI) API 


Required Parameter Group: 


Qualified user space name Char(20) 
Format name Char(8) 
Qualified ILE program name Char(20) 


Error Code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The List ILE Program Information (QBNLPGMI) API gives information about ILE programs, similar to 
the Display Program (DSPPGM) command. The information is placed in a user space specified by you. 


If an original program model (OPM) program is specified for the qualified ILE program name, an error is 
returned and the user space is not changed. 
You can use the QBNLPGMI API to: 

e List modules bound into an ILE program 

e List service programs bound to an ILE program 

e List data items exported to the activation group 

e List data item imports that are resolved by weak exports that were exported to the activation group 


e List copyrights of an ILE program 


Authorities and Locks 


User Space Authority 
*CHANGE 

User Space Library Authority 
*EXECUTE 

User Space Lock 
*EXCLRD 

Program Authority for PGMLO100 and PGMLO0110 Formats 
*USE 

Program Authority for other Formats 
*READ 

Program Library Authority 
*EXECUTE 

Program Lock 
*SHRRD 


Required Parameter Group 
Qualified user space name 
INPUT; CHAR(20) 


The user space that is to receive the ILE program information. The first 10 characters contain the 
user space name, and the second 10 characters contain the name of the library where the user space 
is located. The library name can be a specific library name or one of these special values: 


*CURLIB The job's current library 


*LIBL The library list 


Format name 
INPUT; CHAR(8) 


The content and format of the information to be returned about the specified programs. One of the 
following format names may be used: 


PGMLOI00 ILE program module (*MODULE) information. 
PGMLOIIO_ Variable length ILE program module (*MODULE) information. 


Note: Do not use the generic header entry size for format PGMLO110. Use the 
Size of this entry field returned in this format for the size of each entry. 


PGMLO200 _ ILE service program (*SRVPGM) information. 


PGMLO0300 Data items exported to the activation group (*“ACTGRPEXP). 


PGMLO0400 Data item imports resolved by weak exports that were exported to the activation 
group (*ACTGRPIMP). 


PGMLO500 ILE program copyright (*COPYRIGHT) information. 


Qualified ILE program name 
INPUT; CHAR(20) 


The name of the ILE program for which the information is to be listed. The first 10 characters 
contain the ILE program name, and the second 10 characters contain the name of the library where 
the ILE program is located. 

The ILE program name can be a specific ILE program name or one of the following special values: 


*ALL All ILE programs 


generic* AlJl ILE programs that begin with this generic prefix. For example, WRK* would 
include all ILE programs that begin with WRK. 


The library name can be a specific library name or one of these special values: 


*ALL All libraries in the system 


*ALLUSR _ All non-system libraries 
*CURLIB _ The job's current library 
*LIBL The library list 


*USRLIBL Libraries listed in the user portion of the library list 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of the Generated List 


The user space contains: 
e@ A user area 
e A generic header 
e An input parameter section 
e A header section 


e A list data section 


For details about the user area and generic header, see User Space Format for List APIs. For descriptions of 
each field in the list returned, see Field Descriptions. 


Input Parameter Section 


| Offset 
| Dec Hex |Type Field 


Header Section 


| Offset 
ge He Hex |Type Field 


| CHAR(10) User space name used 


| 10 | A |CHAR(10) [User space library name used | 


PGML0100 Format 


The PGMLO0100 format includes information on all the modules that are bound into the programs specified. 
The modules will be listed in the user space in the order the modules are bound into the program. You must 
have a program authority of *USE to use this format. The following table shows how this information for 
each module is organized. For detailed descriptions of the fields in the list, see Field Descriptions. 


| Offset 
| Dec | Hex /Type Field 


[144 | 90 |CHARGO) |Debugdata —=—=S=~*~<“‘<s—“—S~*S*S*S*S*S*S~S~S~S~S 
[166 | A6 |CHAR@0) [Reserved ~~ ~~  SSOSOSCS 
[200 | C8 |CHARG)  |PTFnumber —~=~=~S~C~*~*~CS~S 
[205 | CD |CHAR® |APARID.—~—~—~—~SCS<TS;«T;«XT;<SC <CS;<CS;«S*# 
[212 | D4 |BINARY@) |ModuleCCSID.—~—~—~—~CS 
[235 | EB |CHARG) [Reserved ~~~SCS~S~S 


[249 | F) |CHARG)  [Storagemodel  ~~~~~SCSCS~S 
| 250 | FA |CHAR(@4) [Reserved ~~~~SCS 
| 324 | 144 |BINARYG@) [Number of SQL statements. ——~—~S~* 
| 356 | 164 |CHAR(O) [Allow copyofdata—~—~CS 
| 366 | 16E |CHAR(O) [Close SQL cursors ~~~SCSCS~S 
[408 | 198 |CHARGO) [Delay PREPARE ——~—~SCS~S~S 
[438 | 1B6 |CHARGO) [SQL packagename —~—~SC~CS~S~S 
[ 448 [ICO |CHAR(I0) [SOL package library name SCS 
| 468 | 1D4 |CHAR(O)  |SQLsort sequence tablename —~—~S~S~* 
| 478 | IDE |CHAR(0) |SQLsomt sequence table library name 
| 488 | 18 |CHAR(O)  |SQLlanguage identifier ——~—~—~SCS~*S 
| 508 | IFC |BINARY@) |SQUpathiengh —~—~SCS~*S 
| 512 | 200 |CHARG483) |SQLpah SOS 


PGMLO0110 Format 


The PGML0O110 format includes information on all the modules that are bound into the programs specified. 
The modules will be listed in the user space in the order the modules are bound into the program. You must 
have a program authority of *USE to use this format. The following table shows how this information for 
each module is organized. For detailed descriptions of the fields in the list, see Field Descriptions. 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


[Offset 
ta c | Hex |Type Field 


[24 | 18 |CHARG0) [Bound module name ——~—~SCS~S 


[148 [94 |CHARGO) [Debugdata—=—=S~*~*~“‘*~*S*S*S*S*S~S~S~S~S 
[ 158 | 9E |CHAR@ [Release module createdon.—~—~—~—~S~*S 
[ 164 | Ad |CHAR@) [Release module createdfor—~S*S 
[170 | AA |CHAR@0) [Reserved ~~~ SCS 
[204 | CC |CHARG)  [PTFnumber ——~—~SCS~S 
[209 | Di |CHAR® |APARID.—————~SCSCS<«;«T;<S;<C;<C;~CS! 
[216 | D& |BINARY@) |ModuleCCSID.——~—~—~S~CSCS 
[ 230 | EF |CHARG) [Reserved ~~ ~~~SCS~S 
[253 | FD |CHARG)  |Storagemodel ~~~~—~SCS*S 
[ 254 | FE |CHARO) [Reserved ~~ ~~~~SCS 
[ 264 | 108 |CHAR@4 [Reserved ~~~ SCS 
[ 308 | 148 |BINARY@) [Number of SQL statements —~—~S~* 
[ 360 | 168 |CHARG0)  |Allowcopyofdata-—~S 
[370 | 172 |CHAR(0) [Close SQL cursors —~—~SCSCS~S~S~S 
[ 300 | 186 |CHARGO)  [Dateformat.-—~=~S~CS*~CS 


| 400 | 190 |CHAR(1) [Date separator 

| 401 | 191 |CHAR(10) [Time format 

| 411 | 19B [CHAR(1) [Time separator 

| 412 | 19C |CHAR(10) [Delay PREPARE 

| 422 | 1A6 |CHAR(10) [Allow blocking 

| 432 | 1BO [CHAR(10) [Default collection name 

| 442 | 1BA [CHAR(10) [SQL package name 

| 452 | 1C4 |CHAR(10) [SQL package library name 

| 462 | 1CE [CHAR(10) [Dynamic user profile 

| 472 | 1D8 |[CHAR(10) [SQL sort sequence table name 
| 482 | 1E2 |CHAR(10) [SQL sort sequence table library name 
| 492 | 1EC [CHAR(10) [SQL language identifier 

| 502 | 1F6 [CHAR(10) [Connection method 

| 512 | 200 [BIN ARY(4) [SQL path length 

| 516 204 [CHAR(3483) [SQL path 

| 1074 432 |CHAR(*) [Reserved 


Bound module information through offsets 


| | [CHAR(*) [Licensed Internal Code options 


PGML0200 Format 


The PGML0200 format includes information on all the service programs that are bound to the programs 
specified. The following table shows how this information is organized. For detailed descriptions of the 
fields in the list, see Field Descriptions. 


| Offset 
| Dec | Hex |Type Field 


PGML0300 Format 


The PGML0300 format lists data items exported to the activation group. The list data items are specified in 
the data export entry in the binding specifications component when the module was created. The following 
table shows how this information is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


a 


[ Dec | Hex |Type |Field 

[| 0 | 0 |CHARCO)  [Programmame = = = = 
| 20 | 14 |BINARY(4) [Size ofdataitemexport = 
| 24 | 18 |BINARY(4)  [DataitemexportnameCCSID = = 
| 28 [ IC |BINARY(4)  [Dataitemexportnamelengh = 


PGML0400 Format 


The PGML0400 format lists data item imports that were resolved by weak exports that had been exported 
to an activation group. The following table shows how this information is organized. For detailed 
descriptions of the fields in the list, see Field Descriptions. 


| Offset 
| Dec | Hex /Type Field 


PGML0500 Format 


The PGML0500 format includes copyright information for the ILE programs specified. The following table 
shows how this information is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


| Offset 
| Dec Hex /Type Field 


[ 28 [ 1C |CHAR@S56) [Copyright 


Field Descriptions 


Allow blocking. Whether blocking will be used to improve the performance of certain SQL statements. 
The possible values are: 


*NONE Blocking is not used. 


*READ Blocking is used for read-only cursors when running COMMIT(*NONE) and there are no 
EXECUTE or EXECUTE IMMEDIATE statements. 


*ALLREAD Blocking is used for all read-only cursors when running COMMIT(*NONE) or 
COMMIT(*CHG). 


Blank The module does not contain SQL statements. 


Allow copy of data. Whether a copy of the data can be used in the implementation of an SQL query. The 
possible values are: 


*NO A copy of the data cannot be used. 
*YES A copy of the data can be used when needed. 
*OPTIMIZE The system determines whether a copy of the data is used for optimal performance. 


Blank The module does not contain SQL statements. 


APAR ID. The module was changed as the result of the authorized program analysis report (APAR) with 
this identification number. This is blank if the module was not changed at bind time. 


Bound module library name. The name of the library containing the module bound into this program at 
bind time. 


Bound module name. The name of the module bound into this program. This is a copy of the module that 
was bound into this program. It is not the *MODULE object on the system. 


Bound service program library name. The name of the library containing the service program bound to 
the program at bind time. This is the library name in which the activation expects to find the service 
program at run time. Hexadecimal zeros indicate the library list is used at the time the service program is 
needed. 


Bound service program name. The name of the service program bound to the program. 


Bound service program signature. The current signature of the service program at the time it was bound 
to the program. 


Close SQL cursors. Specifies when SQL cursors are implicitly closed and SQL-prepared statements are 
implicitly discarded. The possible values are: 


*ENDMOD When the module ends. 
*ENDACTGRP When the activation group is deleted. 


Blank The module does not contain SQL statements. 


Commitment control. The level of commitment control that was specified on the SQL precompile. The 
possible values are: 


*NONE No commitment control was specified on the SQL precompile. Uncommitted changes in other 
jobs can be seen. 


*CHG Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements, and updated, deleted, or inserted rows (records) are locked until the end 
of the unit of work (transaction). Uncommitted changes in other jobs can be seen. 


*CS Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements, and updated, deleted, and inserted rows (records) are locked until the 
end of the unit of work (transaction). A row (record) that is selected but not updated is locked 
until the next row (record) is selected. Uncommitted changes in other jobs cannot be seen. 


*ALL Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements, and all rows selected, updated, deleted, and inserted are locked until the 
end of the unit of work (transaction). Uncommitted changes in other jobs cannot be seen. 


Blank The module does not contain SQL statements. 


Connection method. The method used for establishing remote connections when running distributed 
programs. 


Special values that can be returned are: 


*RUW Only one connection to a relational database is allowed. Consecutive CONNECT statements 
result in the previous connection being disconnected before a new connection is established. 


*DUW Connections to several relational databases are allowed. Consecutive CONNECT statements to 
additional relational databases does not result in disconnection of previous connects. SET 
CONNECTION can be used to switch between connections. Read-only connections may result. 


Blank |The module does not contain SQL statements. 


Copyright. The copyright string included in this program. 
Copyright length. The length of the copyright string. 


Creation data. Whether the bound module has all creation data #*and if that data is observable or 
unobservable. *& 


0 *NO. Not all the creation data is present in the bound module. 
I *YES. The creation data is present in the bound module and all of that data is observable. 


22 *UNOBS. The creation data is present in the bound module but not all of that data is observable. 


Data item export name. Data items that are exported to an activation group. These data items can be used 
outside of the module or program that they are defined in. 


Data item export name CCSID. The coded character set identifier (CCSID) for the name of this data item 
export. 


Data item export name length. The length of the name of the data export item. 


Data item import name. The name of the data item imports that were resolved by weak exports that had 
been exported to the activation group. 


Data item import name CCSID. The coded character set identifier (CCSID) for the name of this data item 


import. 
Data item import name length. The length of the name of the data import item. 
Date format. The format used when accessing date-result columns through SQL. All output date fields are 
returned in this format. For input date strings, the value you specify is used to determine whether the date is 
a valid format. The values returned are: 

*USA USA format (mm/dd/yyyy). 

*[SO International Standards Organization format (yyyy-mm-dd). 

*EUR European format (dd.mm.yyyy). 

*JTS Japanese Industrial Standard Christian Era (yvyyy-mm-dd). 

*MDY Month/day/year format (mm/dd/yy). 

*DMY  Day/month/year format (dd/mm/yy). 

*YMD_Year/month/day format (yy/mm/dd). 

*JUL — Julian format (a numeric value from 1 to 365). 


Blank The module does not contain SQL statements. 


Date separator. The separator used when accessing date-result columns. This information is blank if the 
module does not contain SQL statements; however, the number of SQL statements field should be checked 
to determine if the module contains SQL statements. This is because a blank may be specified as a 
separator value. 


Debug data. Whether debug data was generated when this module was created. If debug data exists, the 
module may be debugged using the source debugger. The possible values are: 


*YES Debug data was generated. 


*NO Debug data was not generated. 


Default collection name. The collection name used for the unqualified names of tables, views, indexes, 
and SQL packages. The possible values are: 


*NONE There is no default collection name. 


Blank The module does not contain SQL statements. 


Delay PREPARE. Whether SQL prepare processing can be delayed until the statement is actually used. 
The possible values are: 


*YES Prepare processing can be delayed. 
*NO Prepare processing cannot be delayed. 


Blank The module does not contain SQL statements. 


Dynamic user profile. The user profile used for dynamic SQL statements. The following special values 
can be returned: 


*USER Local dynamic SQL statements are run under the profile of the module's user. Distributed 
dynamic SQL statements are run under the profile of the SQL package's user. 


*OWNER Local dynamic SQL statements are run under the profile of the module's owner. Distributed 
dynamic SQL statements are run under the profile of the SQL package's owner. 


Blank The module does not contain SQL statements. 


Enable performance collection. The level of performance collection enabled for this module. The 
following values can be returned: 


‘00'X *NONE or '10'X *PEP This gives the entry/exit information for the PEP only. No entry/exit 
hooks in the module's internal procedures and no precall or postcall 
hooks around calls to other procedures are included. 


Note: If *NONE is shown and the module was created or re-created 
on an iSeries server running Version 3 Release 6 Modification 0 prior 
to the installation of PTF MF11968, the module will not have any 
performance collection enabled. To enable performance collection, 
use one of the following commands and specify 
ENBFPRCOL(*PEP): 


e Change Module (CHGMOD) 
e Change Program (CHGPGM) 
e Change Service Program (CHGSRVPGM) 


'50'X *ENTRYEXIT *NONLEAF _ This gives the entry/exit information on all of the non-leaf procedures 
in the module. This includes the PEP routine. This is useful to capture 
information on most routines but not at the expense of destroying the 
‘leaf-ness' of the leaf procedures. 


'70'X *ENTRYEXIT *ALLPRC This gives the entry/exit information on all the procedures of the 
module (including those that were leaf procedures). This includes the 
PEP routine. This is useful to capture information on all procedures. 


'‘DO'X *FULL *NONLEAF This gives the entry/exit information on all the procedures of the 
module that are not leaf procedures. This includes the PEP routine. 
Precall and postcall hooks around calls to external procedures are also 
included. 


'FO'X *FULL *ALLPRC This gives the entry/exit information on all procedures of the module 
(including those that were leaf procedures). This includes the PEP 
routine. Precall and postcall hooks around calls to external procedures 
are also included. This is useful to capture information on all 
procedures. 


Format name specified. The format used to return the ILE program information to the user space. 


Language identifier. Returns the 3-character language identifier used when the module was compiled. The 
following special values can also be returned: 


*JOBRUN The language identifier associated with the job at the time the program that the module is 
bound into runs. 


Blank The module does not contain any language identification information. 


Length of Licensed Internal Code options. The size, in two-byte characters, of the Licensed Internal 
Code options string. This will be 0 if no Licensed Internal Code options were used for this module. 


Licensed Internal Code options. The Licensed Internal Code options that are in use by the module. This 
field is specified in UCS-2 (CCSID 13488). 


Licensed program. If the module was part of a licensed program at bind time, this field shows the product 
number and the level of the licensed program. This is blank if the module is not part of a licensed program 
at bind time. 


Maximum optimization level. The highest level of optimization this module could have at bind time. If 
observability has been removed from the module, this maximum optimization level value might not be the 
same as the one specified when the module was created. Possible values are: 


65535 The module is not restricted to a maximum optimization level. It can be retranslated to any of 
the supported optimization levels. 65535 is also known as *NOMAX. 


40 Maximum level of optimization. This level includes all the optimizations performed at 
optimization level 30. In addition, it includes optimization that disables call and instruction 
tracing. Thus, tracing of modules created at this optimization level cannot be done. 


30 More optimization is performed in addition to those performed at optimization level 20. 
Variables cannot be changed but can be displayed while the program is being debugged. 
However, the displayed value of the variable during debugging may not be its actual value. 30 is 
also known as *FULL. 


20 Some optimization is performed on the generated code. When the module optimized at this level 
is being debugged, the variables can be displayed but not changed. This level improves the 
performance of the module slightly over level 10. 20 is also known as *BASIC. 


10 No additional optimization is performed on the generated code. Variables can be displayed and 
changed when the program is being debugged. With no optimization of the code, this value 
provides the lowest level of module performance. 10 is also known as *NONE. 


Module attribute. The language used in the module. This field can be blank (for example, when a module 
is created by a compilation process internal to IBM). 


Module CCSID. The coded character set identifier (CCSID) for this module. 


Module creation date and time. The date and time the module was created. The creation date and time 
field is in the CY YMMDDHHMMSS format as follows: 


C Century, where 0 indicates years 19xx and 1 indicates years 20xx. 
YY Year 

MM Month 

DD Day 

HH Hour 

MM Minute 

SS Second 


Naming convention. The convention used for naming objects in SQL statements. The possible values are: 


*SQL The SQL naming convention is used. 
*SYS The system naming convention is used. 


Blank The module does not contain SQL statements. 


Number of procedures. The number of procedures defined in the module. This number includes the 
program entry procedure (PEP), if one was generated by the compiler for this module. 


Number of procedures block-order measured. The number of procedures defined in the module that had 
block-order profiling data collected at the time block-order profiling data was applied. If the module does 
not have block-order profiling data applied, this value will be zero. 


Number of procedures block reordered. The number of procedures defined in the module that are block 
reordered. If the module does not have block-order profiling data applied, this value will be zero. This value 
can decrease if the program that this bound module is contained in is retranslated. 


Number of SQL statements. The number of SQL statements contained in the module. This value is zero if 
the module does not contain SQL statements. 


Object control level. The object control level for the module at the time it was bound into this program. 
You can compare the object control level of a module to the object control level of a listing to make sure 
the listing matches the module. 


Offset to Licensed Internal Code options. The offset from the beginning of the user space where the 
Licensed Internal Code options begin for this bound module. This will be 0 if no Licensed Internal Code 
options were used for this module. 


Optimization level. Optimization levels cause the translator to produce machine code that reduces the 
amount of system resources necessary to run the program. The more optimization, the more efficiently the 
module runs on the system. Also, with more optimization you may not be able to change or view variables 
that have been optimized. The possible values are: 


65535 The module is not restricted to a maximum optimization level. It can be retranslated to any of 
the supported optimization levels. 65535 is also known as *NOMAX. 


40 Maximum level of optimization. This level includes all the optimizations performed at 
optimization level 30. In addition, it includes optimization that disables call and instruction 
tracing. Thus, tracing of modules created at this optimization level cannot be done. 


30 More optimization is performed in addition to those performed at optimization level 20. 
Variables cannot be changed but can be displayed while the program is being debugged. 
However, the displayed value of the variable during debugging may not be its actual value. 30 is 
also known as *FULL. 


20 Some optimization is performed on the generated code. When the module optimized at this level 
is being debugged, the variables can be displayed but not changed. This level improves the 
performance of the module slightly over level 10. 20 is also known as *BASIC. 


10 No additional optimization is performed on the generated code. Variables can be displayed and 
changed when the program is being debugged. With no optimization of the code, this value 
provides the lowest level of module performance. 10 is also known as *NONE. 


Profiling data. The profiling data attribute for the module bound into this program. Possible values are: 


*NOCOL The collection of profiling data is not enabled and block-order profiling data is not 
applied to the module bound into this program. 


*COL The collection of profiling data is enabled. Any applied block-order profiling data has 
been removed for the module bound into this program. 


*APYBLKORD  Block-order profiling data is applied to the module bound into this program. See the 


number of procedures block reordered field for the current number of procedures in 
this module that are block reordered. 


Program library name. The name of the library containing the program. 


Program library name specified. The program library name that was passed to this API on the call in the 
qualified ILE program name and library parameter. 


Program name. The name of the program. 


Program name specified. The program name that was passed to this API on the call in the qualified ILE 
program name and library parameter. 


PTF number. The program temporary fix (PTF) that resulted in the creation of the module. This field is 
blank for user-created modules. 


Relational database. The default relational database that was specified on the SQL precompile. A 
nonblank value other than *LOCAL specifies the name of the relational database to be resolved through the 
relational database directory. The following special values can be returned: 


*LOCAL The module can only access data on the local system. 


Blank The module does not contain SQL statements. 


Release module created for. The version, release, and modification level of the operating system for 
which the module was created. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr — The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


Release module created on. The version, release, and modification level of the operating system on which 
the module was created. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr — The character R is followed by a 1-character release level. 


Mm The character M is followed by a 1-character modification level. 


Reserved. An ignored field. 

Size of data item export. The size, in bytes, of the data item export. 

Size of this entry. The size, in bytes, of this entry. 

Sort sequence table library name. The name of the library that is used to locate the sort sequence table. 


This information is blank if the module does not contain any sort sequence information or a special value 
was returned for the sort sequence table name. The following special values can be returned: 


*LIBL The sort sequence table is found in the library list when the ILE program runs this module. 


*CURLIB The sort sequence table is found in the current library when the ILE program runs this 
module. 


Sort sequence table name. The name of the sort sequence table and the library used when the module was 
compiled. This does not apply to SQL statements in the module. The following special values can be 
returned: 


*HEX No sort sequence is used. 


*JOBRUN The sort sequence is the sort sequence value associated with the job at the time the ILE 
program runs this module. 


*LANGIDSHR _ The shared sort sequence for the language identifier is used. 
*LANGIDUNQ The unique sort sequence for the language identifier is used. 


Note: This sort sequence table does not apply to SQL statements. 


Source file library name. The name of the library that contains the source file used to create the module. 
The field is blank if no source file was used to create the module. 


Source file member name. The name of the member in the source file. The field is blank if no source file 
was used to create the module. 


Source file name. The name of the source file used to create the module. The field is blank if no source file 
was used to create the module. 


Source file updated date and time. The date and time the member in the source file was last updated. The 
field is in the same format as the module creation date and time field. The field is blank if no source file 
was used to create the module. 


SQL language identifier. Returns the 3-character language identifier used when the module was compiled. 
This information is blank if the module does not contain any language identification information. The 
following possible special value can also be returned: 


*JOBRUN _ The language identifier is the LANGID associated with the job at the time the module is 
run. 


SQL package library name. The name of the library the SQL package is in. 


SQL package name. The name of the SQL package created on the relational database specified on the 
RDB parameter of the command that created this module. The possible values are: 


*NONE There is no default collection name. 


Blank The module does not contain SQL statements. 


SQL path. The list of libraries used during resolution of functions and data types within SQL statements. 
The list is in the form of repeating library names, each surrounded by double quotes and separated by 
commas. Even though 3843 bytes are reserved, the path's length is determined by the SQL path length 
entry. 


SQL path length. The length, in bytes, of the SQL path. 


SQL sort sequence table library name. The name of the library that is used to locate the SQL sort 


sequence table. This information is blank if the module does not contain any SQL sort sequence 
information or a special value was returned for the SQL sort sequence table name. The following special 
values can be returned: 


*LIBL The SQL sort sequence table is found by looking in the library list. 


*CURLIB The SQL sort sequence table is found by looking in the current library. 


SQL sort sequence table name. The name of the table name used when the module was compiled. This 
information is blank if the module does not contain any SQL sort sequence information. The following 
special values can be returned: 


*HEX No SQL sort sequence is used for the SQL statements. 


*JOBRUN The SQL sort sequence is the SRTSEQ value associated with the job at the time the 
SQL statements within the module are run. 


*LANGIDSHR _ The shared SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


*LANGIDUNQ _ The unique SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


Storage model. Where the automatic and static storage for this bound module is allocated at run time. The 
following values can be returned: 


0 *SNGLVL Automatic and static storage are allocated from single-level storage. 
1 *TERASPACE Automatic and static storage are allocated from teraspace. 


2 *INHERIT Automatic and static storage are allocated from either single-level storage or 
teraspace, depending on the activation. 


Teraspace storage enabled. The teraspace storage capability for this bound module. Possible values are: 
‘00'X *NO The module bound to this program is not teraspace storage enabled. 


‘80'X *YES The module bound to this program is teraspace storage enabled. 


Time format. The format used when accessing time-result columns through SQL. All output time fields are 
returned in this format. The values returned are: 


*USA USA format (hh:mm a.m. or p.m.). 
*I[SO International Standards Organization format (hh.mm.ss). 
*EUR European format (hh.mm.ss). 
*JIS Japanese Industrial Standard Christian Era (hh.mm.ss). 
*HMS  Hours/minutes/seconds format (hh:mm:ss). 
Blank The module does not contain SQL statements. 
Time separator. The separator used when accessing time-result columns. This information is blank if the 


module does not contain SQL statements; however, the number of SQL statements field should be checked 
to determine if the module contains SQL statements. This is because a blank may be specified as a 


separator value. 
User-modified. Whether the module was changed by the user at bind time. The possible values are: 
0 The user did not change the module. 


I The user changed the module. 


User space library name specified. The user space library name that was passed to this API on the call in 
the qualified user space name parameter. 


User space library name used. The name of the library that contains the user space that receives the ILE 
program information requested. 


User space name specified. The user space name that was passed to this API on the call in the qualified 
user space name parameter. 


User space name used. The name of the user space that receives the ILE program information requested. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C20 E Error found by program &1. 

CPF3C21 E Format name &1 is not valid. 

CPF3C90 E Literal value cannot be changed. 

CPF3CAA E List is too large for user space &1. 

CPF3CF1 E Error code parameter not valid. 

CPF5CF5 E &1 in library &2 not bound program. 

CPF5CF6 E Program name &1 not valid special value. 
CPF811A E User space &4 in &9 damaged. 

CPF9570 E Error occurred creating or accessing debug data. 
CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 

CPF9803 E Cannot allocate object &2 in library &3. 

CPF9804 E Object &2 in library &3 damaged. 

CPF9806 E Cannot perform function for object &2 in library &3. 
CPF9807 E One or more libraries in library list deleted. 
CPF9808 E Cannot allocate one or more libraries on library list. 


CPF9810 E 
CPF9811 E 
CPF9820 E 
CPF9821 E 
CPF9830 E 
CPF9838 E 
CPF9872 E 


Library &1 not found. 

Program &1 in library &2 not found. 

Not authorized to use library &1. 

Not authorized to program &1 in library &2. 
Cannot assign library &1. 

User profile storage limit exceeded. 


Program or service program &1 in library &2 ended. Reason code &3. 


API introduced: V2R3 


Top | Program and CL Command APIs | APIs by category 


List Module Information (Q@8NLMODI) API 


Required Parameter Group: 


Qualified user space name Char(20) 
Format name Char(8) 
Qualified module name Char(20) 
Error code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The List Module Information (QBNLMODI) API lists information about modules. The information is 
placed in a user space specified by you. This API is similar to the Display Module (DSPMOD) command. 


You can use the QBNLMODI API to: 


List the symbols defined that can be exported to other modules 


List the symbols that are defined external to the module 
List procedure names and their type 
List objects that are referenced when the module is bound into an ILE program or service program 


List copyright information 


Authorities and Locks 


User Space Authority 
*CHANGE 
User Space Library Authority 
*EXECUTE 
User Space Lock 
*EXCLRD 
Module Authority 
*USE 
Module Library Authority 
*EXECUTE 
Module Lock 
*SHRRD 


Required Parameter Group 
Qualified user space name 
INPUT; CHAR(20) 


The user space that is to receive the module information. The first 10 characters contain the user 
space name. The second 10 characters contain the name of the library where the user space is 
located. The library name can be a specific library name or one of these special values: 


*CURLIB The job's current library 
*LIBL The library list 


Format name 
INPUT; CHAR(8) 


The content and format of the information to be returned about the specified modules. One of the 
following format names may be used: 


MODLO100 Format Module export (*“EXPORT) information. 


MODLO200 Format Module import (*IMPORT) information. 


MODLO300 Format Module procedures (*PROCLIST) information. 


MODLO400 Format Referenced system objects (*REFSYSOBJ) information. 


MODLO500 Format Module copyright (*COPYRIGHT) information. 


Note: Do not use the generic header entry size for formats returned by this API. Use the Size of this 
entry field returned in each format for the size of each entry. 


Qualified module name 
INPUT; CHAR(20) 
The name of the module for which the information is to be listed. The first 10 characters contain 
the module name. The second 10 characters contain the name of the library where the module is 
located. 
The module name can be a specific module name or one of the following special values: 


*ALL All modules 


generic* All modules that begin with this generic prefix. For example, WRK* lists information 
for all modules that begin with WRK to which you are authorized. 


The library name can be a specific library name or one of these special values: 
*ALL All libraries in the system 
*ALLUSR _ All non-system libraries 
*CURLIB The job's current library 


*LIBL The library list 


*USRLIBL Libraries listed in the user portion of the library list 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of the Generated List 


The user space contains: 

e A user area 

e@ A generic header 

e An input parameter section 
e A header section 
® 


A list data section 


For details about the user area and generic header, see User Space Format for List APIs. For descriptions of 
each field in the list returned, see Field Descriptions. 


Note: Do not use the generic header entry size for formats returned by this API. Use the Size of this entry 
field returned in each format for the size of each entry. 


Input Parameter Section 


[Offset 
Le c | Hex |Type Field 


Header Section 


| Offset 
_ c | Hex |Type Field 


| | |[CHAR(10) [User space name used 
| 10 | A |CHAR(10) [User space library name used 


MODLO0100 Format 


The MODLO100 format lists the symbols defined in the module and that are exported to other modules. The 
following table shows how this information for each module is organized. For detailed descriptions of the 
fields in the list, see Field Descriptions. 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


| Offset 
| Dec | Hex /|Type Field 


| 0 | 0 [BIN ARY(4) [Size of this entry 

| 4 | 4 |[CHAR(10) [Module name 

| 14 | E [CHAR(10) [Module library name 

| 24 | 18 |CHAR(1) [Exported defined symbol type 

| 25 | 19 [CHAR(G3) [Reserved 

| 28 1C [BINARY (4) [Offset to exported defined symbol name 
| 32 | 20 [BIN ARY(4) [Length of exported defined symbol name 
| 36 | 24 |[CHAR(10) [Uses argument optimization (ARGOPT) 
| 46 | 2E [CHAR(*) [Reserved 


Module information through offsets 


| | [CHAR(*) [Exported defined symbol name 


MODLO0200 Format 


The MODL0200 format lists symbols defined external to the module. The following table shows how this 
information for each module is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


[Offset 
= c | Hex |Type Field 


| | [BINARY(4) [s ize of this entry 

| 4 | 4 [CHAR(10) [Module name 

| 14 | E |[CHAR(10) [Module library name 

| 24 | 18 |CHAR(1) [Imported (unresolved) symbol type 

| 25 | 19 [CHAR(3) [Reserved 

| 28 | 1C [BINARY(4) [Offset to imported (unresolved) symbol name 
| 32 | 20 [BINARY (4) [Length of imported (unresolved) symbol name 
| 36 | 24 [CHAR(10) [Uses argument optimization (ARGOPT) 

| 46 | 2E [CHAR(*) [Reserved 


Module information through offsets 


| | [CHAR(*) [Imported (unresolved) symbol name 


MODL0300 Format 


The MODL0300 format lists procedure names and their types. The following table shows how this 
information for each module is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


| Offset 
a c | Hex |Type Field 


| [BIN ARY(4) [s ize of this entry 

| 4 | 4 |CHAR(10) [Module name 

| 14 | E [CHAR(10) [Module library name 

| 24 | 18 |CHAR(1) [Procedure type 

| 25 | 19 |CHARG) [Reserved 

| 28 | 1C [BIN ARY(4) [Offset to procedure name 

| 32 | 20 [BIN ARY(4) [Length of procedure name 

| 36 | 24 |CHAR(10) [Uses argument optimization (ARGOPT) 
| 46 | 2E [CHAR(*) [Reserved 


Module information through offsets 


| | |CHAR(*) [Procedure name 


MODL0400 Format 


The MODL0400 format lists the objects that are referenced by the module when the module is bound to an 
ILE program or service program. The following table shows how this information for each module is 
organized. For detailed descriptions of the fields in the list, see Field Descriptions. 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


[Offset 
Lt c | Hex |Type Field 


| 24 | 18 |CHAR(IO) = [Objecttype 


Module information through offsets 


CHAR(*) Object name 
P| ICHAR@) JObjectname 


MODLO0500 Format 


The MODL0500 format lists the copyrights contained in the module. The following table shows how this 
information for each module is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


| Offset 
| Dec Hex /Type Field 


| 0 0 BINARY(4) Size of this entry 

| 4 4 CHAR(10) [Module name 

| 14 E CHAR(10) Module library name 
| 24 18 |BINARY(4) Offset to copyright 

| 28 1C_ |BINARY(4) [Length of copyright 
| 32 20 |CHAR(*) Reserved 


Module information through offsets 


| [CHAR(*) Copyright 


Field Descriptions 


Copyright. Copyright information for the module. 


Exported defined symbol name. An exported procedure or variable in this module. Other modules may 
use these symbols. 


Exported defined symbol type. Indicates whether the exported symbol is a procedure or a data symbol. 
The possible values are: 


‘00'X The exported symbol is a procedure. 


‘OI'X The exported symbol is a data item. 


Format name specified. The format name that was passed to this API on the call in the format parameter. 


Imported (unresolved) symbol name. An imported procedure or variable in this module. This is typically 
a reference to a procedure exported from another module. 


Imported (unresolved) symbol type. Indicates whether the imported symbol is a procedure or a data 
symbol. The possible values are: 


‘00'X The imported symbol is a procedure. 


‘Ol'X The imported symbol is a data item. 


Length of copyright. The length of the copyright. 

Length of exported defined symbol name. The length of the exported defined symbol name. 

Length of imported (unresolved) symbol name. The length of the imported (unresolved) symbol name. 
Length of object name. The length of the object name. 

Length of procedure name. The length of the procedure name. 

Module library name. The name of the library containing the module. 


Module library name specified. The module library name that was passed to this API in the qualified 
module name parameter. 


Module name. The name of the module. 


Module name specified. The module name that was passed to this API in the qualified module name 
parameter. 


Object library name. The name of the library where the object exists. If the object library name is blank, 
the object is in the integrated file system. 


Object name. A system object that is referenced at bind time. This object (modules and/or service 
programs and/or binding directories) is used by CRTPGM or CRTSRVPGM when this module is listed on 
the MODULE parameter on CRTPGM or CRTSRVPGM. 


Object type. The object type of the system object that is referenced at bind time. The possible special 
values are: 


*MODULE The object is a module. 
*SRVPGM _ The object is a service program. 


*BNDDIR _ The object is a binding directory. 


Offset to copyright. Offset from the beginning of the user space to the copyright for this entry. 


Offset to exported defined symbol name. Offset from the beginning of the user space to the exported 
defined symbol name for this entry. 


Offset to imported (unresolved) symbol name. Offset from the beginning of the user space to the 
imported (unresolved) symbol name for this entry. 


Offset to object name. Offset from the beginning of the user space to the object name for this entry. 


Offset to procedure name. Offset from the beginning of the user space to the procedure name for this 
entry. 


Procedure name. A procedure defined in this module. 
Procedure type. The type of procedure. The possible values are: 


‘00'X Regular procedure. If the type is regular, this procedure cannot serve as a program entry 
procedure. 


‘Ol'X Entry point procedure. If the type is entry point, this procedure can serve as a program entry 
procedure when this module is bound to a program. 


Reserved. An ignored field. 


Size of this entry. The size, in bytes, of this entry. Do not use the generic header entry size for formats with 
this field. Use this field for the size of each entry. 


User space library name specified. The user space library name that was passed to this API on the call in 
the qualified user space name parameter. 


User space library name used. The name of the library that contains the user space that receives the 
module information requested. 


User space name specified. The user space name that was passed to this API on the call in the qualified 
user space name parameter. 


User space name used. The name of the user space that receives the module information requested. 


Uses argument optimization (ARGOPT). Whether or not the procedure import or export uses argument 
optimization. For data imports and exports, this value has no meaning and is always given as a blank. For 
some procedure imports, this value cannot be determined and is given as *UNKNOWN. Possible values 
follow: 


*YES The procedure import or export uses argument optimization (ARGOPT) 
*NO The procedure import or export does not use argument optimization (ARGOPT) 


*UNKNOWN The procedure import is used only to construct procedure pointers and is never called 
directly. 


Blank The symbol is not a procedure import or export. 


Error Messages 


Message ID Error Message Text 

CPDSCFE E Module &1 in library &2 is in error. 
CPF24B4 E Severe error while addressing parameter list. 
CPF3C20 E Error found by program &1. 

CPF3C21E Format name &1 is not valid. 

CPF3C90 E Literal value cannot be changed. 

CPF3CAA E List is too large for user space &1. 
CPF3CF1 E Error code parameter not valid. 

CPF5CED E Module name &1 not a valid special value. 


CPFS5CFE E Module &1 in file &2 not changed. 


CPF811A E 
CPF8122 E 
CPF8123 E 
CPF8130 E 
CPF9801 E 
CPF9802 E 
CPF9803 E 
CPF9804 E 
CPF9806 E 
CPF9807 E 
CPF9808 E 
CPF9810 E 
CPF9811 E 
CPF9820 E 
CPF9821 E 
CPF9830 E 
CPF9838 E 


User space &4 in &9 damaged. 

&8 damage on library &4. 

Damage on object information for library &4. 
Character in quoted name not valid. 

Object &2 in library &3 not found. 

Not authorized to object &2 in &3. 

Cannot allocate object &2 in library &3. 

Object &2 in library &3 damaged. 

Cannot perform function for object &2 in library &3. 
One or more libraries in library list deleted. 

Cannot allocate one or more libraries on library list. 
Library &1 not found. 

Program &1 in library &2 not found. 

Not authorized to use library &1. 

Not authorized to program &1 in library &2. 
Cannot assign library &1. 


User profile storage limit exceeded. 


API Introduced: V3R7 


Top | Program and CL Command APIs | APIs by category 


List Service Program Information (Q8BNLSPGM) 
API 


Required Parameter Group: 


Qualified user space name Char(20) 
Format name Char(8) 
Qualified service program name Char(20) 


Error Code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The List Service Program Information (QBNLSPGM) API gives information about service programs, 
similar to the Display Service Program (DSPSRVPGM) command. The information is placed in a user 
space specified by you. 
You can use the QBNLSPGM API to: 

e List modules bound into a service program 
List service programs bound to a service program 
List data items exported to the activation group 
List data item imports that are resolved by weak exports that were exported to the activation group 
List copyrights of a service program 
List procedure export information of a service program 


List data export information of a service program 


List signatures of a service program 


Authorities and Locks 


User Space Authority 
*CHANGE 

User Space Library Authority 
*EXECUTE 

User Space Lock 
*EXCLRD 

Service Program Authority for SPGLO100 and SPGLO110 Formats 
*USE 

Service Program Authority for other Formats 
*READ 

Service Program Library Authority 


*EXECUTE 
Service Program Lock 
*SHRRD 


Required Parameter Group 

Qualified user space name 
INPUT; CHAR(20) 
The user space that is to receive the service program information. The first 10 characters contain 
the user space name. The second 10 characters contain the name of the library where the user space 
is located. The library name can be a specific library name or one of these special values: 


*CURLIB The job's current library 


*LIBL The library list 


Format name 
INPUT; CHAR(8) 


The content and format of the information to be returned about the specified service program(s). 
One of the following format names may be used: 


SPGLOIOO Service program module (*MODULE) information. 
SPGLOIIO Service program module (*MODULE) information. 


Note: Do not use the generic header entry size for format SPGLO110. Use the Size 
of this entry field returned in this format for the size of each entry. 


SPGLO200 Service program (*SRVPGM) information. 
SPGLO300 Data items exported to the activation group (*“ACTGRPEXP). 


SPGLO400_ Data item imports resolved by weak exports that were exported to the activation 
group (*“ACTGRPIMP). 


SPGLOS500_ Service program copyright (*COPY RIGHT) information. 
SPGLO600_ Service program procedure export (*“PROCEXP) information. 
SPGLO6I0 Service program long procedure export name (*PROCEXP) information. 


Note: Do not use the generic header entry size for format SPGL0610. Use the Size 
of this entry field returned in this format for the size of each entry. 


SPGLO700_ Service program data export (*DTAEXP) information. 


SPGLOS800 Service program signature (*“SIGNATURE) information. 


Qualified service program name 


INPUT; CHAR(20) 


The name of the service program for which the information is to be listed. The first 10 characters 
contain the service program name. The second 10 characters contain the name of the library where 
the service program is located. 


The service program name can be a specific service program name or one of the following special 
values: 


*ALL All service programs 


generic* All service programs that begin with this generic prefix. For example, WRK* lists 
information for all service programs that begin with WRK to which you are 
authorized. 


The library name can be a specific library name or one of these special values: 
*ALL All libraries in the system 
*ALLUSR All non-system libraries 
*CURLIB The job's current library 
*LIBL The library list 


*USRLIBL Libraries listed in the user portion of the library list 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of the Generated List 


The user space contains: 
e A user area 
e A generic header 
e An input parameter section 
e A header section 


e A list data section 


For details about the user area and generic header, see User Space Format for List APIs. For descriptions of 
each field in the list returned, see Field Descriptions. 


Input Parameter Section 


| Offset 
| Dec Hex /Type Field 


Header Section 


| Offset 
| Dec | Hex /Type Field 


| 0 | 0 [CHAR(10) [User space name used 
| 10 | A |CHAR(10) [User space library name used 
| 20 | 14 [BINARY (4) [Reason code 


SPGLO0100 Format 


The SPGLO100 format includes information on all the modules that are bound into the programs specified. 
The modules are listed in the user space in the order the modules are bound into the program. You must 
have a service program authority of *USE to use this format. The following table shows how this 
information for each module is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


| Offset 
| Dec | Hex /Type Field 


| 0 | 0 [CHAR(10) [Service program name 

| 10 | A |CHAR(10) [Service program library name 

| 20 | 14 |CHAR(10) [Bound module name 

| 30 1E [CHAR(10) [Bound module library name 

| 40 28 |CHAR(10) [Source file name 

| 50 | 32 |CHAR(10) [Source file library name 

| 60 | 3C |[CHAR(10) [Source file member name 

| 710 | 46 |CHAR(10) [Module attribute 

| 80 | 50 |CHAR(13) [Module creation date and time 

| 93 | 5D [CHAR(13) [Source file updated date and time 
| 106 6A [CHAR(10) [Sort sequence table name 

| 116 | 74 |CHAR(10) [Sort sequence table library name 
| 126 | TE [CHAR(10) [Language identifier 

| 136 | 88 [BIN ARY(4) [Optimization level 

| 140 | 8C [BINARY(4) [Maximum optimization level 

| 144 | 90 [CHAR(10) [Debug data 


[ 154 [9A [CHAR@®) [Release module createdon—~—~S~*S 
[ 160 | AO |CHAR@) [Release module createdfor.—~—~S~*S 
[ 166 | A6 |CHAR@0) [Reserved ~~ SSCS 
[200 | C8 |CHARG)  [PTFmumber —~—~=~S~C~S*~*~CS 
[205 | CD |CHAR® |APARID.——~—~—~—~SCSCS<«S«T;<;<C;<CS;<CS*S*# 
[212 | D4 |BINARY@) |ModuleCCSID.—~—~CS~S~S 
[235 | EB |CHARG) [Reserved ~~~~SCS 
[249 | F9 |CHARG)  [Storagemodel ~~SCS*S 
[250 | FA |CHARC4) [Reserved ~~SCS 
[ 304 | 144 |BINARY@) [Number of SQL statements —~—~S~*S 
| 356 | 164 |CHAR(0) [Allow copyofdata~—~—~SCS 
[ 366 | 162 |CHARG0)  |CloseSQLeursor~—~CS~S~*~CS 
[ 386 | 182 |CHARGO) [Dateformat +S 
[306 | 18C |CHARG)  |Dateseparator=~=~CS~*~<CS~S*S 
[408 | 198 |CHARGO) [Delay PREPARE ——~—~SCS~S 
[ 438 | 1B6 |CHARGO) [SQL packagename —~—~S~CS*S 
[ 448_| ICO |CHARGO) [SOL package library name ——~—~S~S~S~S~*S 
| 468 | 1D4 |CHAR(0) |SQLsom sequence tablename ———~—S~*S 
| 478 | IDE |CHAR(0) _ |SQLsomt sequence table library name 
[ 488 | 1E8 |CHARGO)  |SQLlanguage identifier ———~—~SCS~S 
| 508 | IFC |BINARY@) |SQUpathiengh —~—~—~SCS~S 
[512 | 200 |CHARG483) |SQcpah 


SPGL0O110 Format 


The SPGLO110 format includes information on all the modules that are bound into the programs specified. 
The modules are listed in the user space in the order the modules are bound into the program. You must 
have a service program authority of *USE to use this format. The following table shows how this 
information for each module is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


| Offset 
| Dec | Hex |Type Field 


| 0 | 0 [BINARY(4) [Size of this entry 

| 4 | 4 |[CHAR(10) [Service program name 

| 14 | E |CHAR(10) [Service program library name 
| 24 | 18 [CHAR(10) [Bound module name 

| 34 | 22 |[CHAR(10) [Bound module library name 

| 44 2C |CHAR(10) [Source file name 

| 54 | 36 [CHAR(10) [Source file library name 

| 64 | 40 |CHAR(10) [Source file member name 

| 74 | 4A |CHAR(10) [Module attribute 

| 84 | 54 [CHAR(13) [Module creation date and time 
| 97 | 61 [CHAR(13) [Source file updated date and time 
| 110 | 6E |CHAR(10) [Sort sequence table name 

| 120 | 78 [CHAR(10) [Sort sequence table library name 
| 130 | 82 |[CHAR(10) [Language identifier 

| 140 8C [BIN ARY(4) [Optimization level 

| 144 | 90 [BINARY(4) [Maximum optimization level 

| 148 | 94 |CHAR(10) [Debug data 

| 158 | OF |CHAR(6) [Release module created on 

| 164 | A4 [CHAR(6) [Release module created for 

| 170 | AA [CHAR(20) [Reserved 

| 190 | BE |CHAR(1) |User-modified 

| 191 | BF [CHAR(13) [Licensed program 

| 204 | CC [CHAR(S) [PTF number 

| 209 | D1 |CHAR(©) |APAR ID 

| 215 | D7 [CHAR(1) [Creation data 

| 216 | D8 [BINARY(4) [Module CCSID 

| 220 | DC |CHAR(8) [Object control level 

| 228 | E4 [CHAR(1) [Enable performance collection 
| 229 | E5 |[CHAR(10) [Profiling data 

| 239 | EF |CHAR(1) [Reserved 


[253 | FD |CHARG)  |Storagemodel = ~=~SOCS~*~*~CS 
[254 | FE |CHAR@) [Reserved ~=~SOC~*~CS*S 
[ 264 | 108 |CHAR@) [Reserved ~SOSOSC~CS 
[ 328 | 148 [BINARY@) [Number of SQL statements. —~—~S~S~S~*S 
| 360 | 168 |CHAR(IO) [Allow copyofdata—~—~SCS*S 
| 370 | 172 |CHAR(O)  |CloseSQL cursor ~—~S~SCS 
[ 401 | 191 |CHARGO)  [Timeformat=—~=~=~S~S*~*~<“<S~S*~S 
| 412 | 19C |CHAR(O) [DelayPREPARE——~—~SCS~S 
[ 422 | 1A6 |CHARCO)  |Allowblocking —~—~=~CS~*~*~S 
| 442 | IBA |CHARGO) [SQL packagename —~—~S~S~S~*S 
| 452 | 1c4 |CHAR(0) [SQL package library name —~—~S~S~S~S~S 
[ 472 | 1D8 |CHARG0)  |SQLsort sequence table name ——~—~S~*S 
[ 482 | 1E2 |CHAR(0) _|SQLsom sequence table library name 
[ 492 | TEC |CHARGO) [SQL language identifier —~—~—~S~S~S 
[ 512 | 200 |BINARY@) |SQUpathiengh ~~~SOSCSCS~S 
| 516 | 204 |CHARG483) |SQbpah SCS 
[1074 | 432 |CHAR@) [Reserved ~~~SOC~CS*S 


SPGLO0200 Format 


The SPGLO0200 format includes information on all the service programs that are bound to the programs 
specified. The following table shows how this information is organized. For detailed descriptions of the 
fields in the list, see Field Descriptions. 


[Offset 


[| Dec | Hex [Type |Field 

[| 0 | 0 |CHARCO) ~~ |Serviceprogramname = = = = = 
[| 10 [ A  |CHAR(O) [Service program libraryname = 
| 20 | 14 |CHARCO0) [Bound service programname == 
| 40 [ 28 |CHAR(I6) — [Bound service program signature == 


SPGL0300 Format 


The SPGLO0300 format lists data items exported to the activation group. The list data items are specified in 
the data export entry in the binding specifications component when the module was created. The following 
table shows how this information is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


| Offset 
ae c | Hex |Type Field 


SPGL0400 Format 


The SPGL0400 format lists data item imports that were resolved by weak exports that had been exported to 
an activation group. The following table shows how this information is organized. For detailed descriptions 
of the fields in the list, see Field Descriptions. 


| Offset 
| Dec | Hex /|Type Field 


SPGL0500 Format 


The SPGLO500 format includes copyright information for the service programs specified. The following 
table shows how this information is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


| Offset 
ape Hex |Type Field 


SPGL0600 Format 


The SPGL0600 format includes procedure export information for the service programs specified. The 
following table shows how this information is organized. 


Note: Check the subsetted list indicator in the generic header to determine if all the information that was 
available was returned. If the subsetted list indicator indicated there was data available that could not be 
returned, check the reason code in the header section for further details. For detailed descriptions of the 
fields in the list, see Field Descriptions. 


| Offset 
=e Hex |Type Field 


SPGL0610 Format 


The following information is returned for the SPGL0610 format. All procedure export names available are 
returned in the SPGL0610 format, regardless of the size of the name. For detailed descriptions of the fields 
in the table, see . 


Note: Do not use the generic header entry size for this format. Use the Size of this entry field returned in 
this format for the size of each entry. 


| Offset 
| Dec Hex /Type Field 


| 46 | 28 |CHAR@ [Reserved ~~ ~~~SCS 


Service program information through offsets 


| [CHAR(*) [Long procedure export name 


SPGLO0700 Format 


The SPGLO700 format includes data export information for the service programs specified. The following 
table shows how this information is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


| Offset 
| Dec | Hex |Type Field 


SPGLO0800 Format 


The SPGLO0800 format includes signature information for the service programs specified. The following 
table shows how this information is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


| Offset 
a c | Hex |Type Field 


| |CHAR(10) [s ervice program name 
| 10 | A |CHAR(10) [Service program library name 
| 20 | 14 [CHAR(16) [Signature 


Field Descriptions 


Allow blocking. Whether blocking is used to improve the performance of certain SQL statements. The 
possible values are: 


*NONE Blocking is not used. 


*READ Blocking is used for read-only data cursors when running COMMIT(*NONE) and there 
are no EXECUTE or EXECUTE IMMEDIATE statements. 


*ALLREAD Blocking is used for all read-only cursors when running COMMIT(*NONE) or 
COMMIT(*CHG). 


Blank The module does not contain SQL statements. 


Allow copy of data. Whether a copy of the data can be used in the implementation of an SQL query. The 
possible values are: 


*NO A copy of the data cannot be used. 
*YES A copy of the data can be used when needed. 
*OPTIMIZE The system determines whether a copy of the data is used for optimal performance. 


Blank The module does not contain SQL statements. 


APAR ID. The module was changed as the result of the authorized program analysis report (APAR) with 
this identification number. This is blank if the module was not changed at bind time. 


Bound module library name. The name of the library containing the module bound into this service 
program at bind time. 


Bound module name. The name of the module bound into this service program. This is a copy of the 
module that was bound into this service program. It is not the *MODULE object on the system. 


Bound service program library name. The name of the library containing the service program bound to 
this service program at bind time. This is the library name in which the activation expects to find the service 
program at run time. Hexadecimal zeros indicate the library list is used at the time the service program is 
needed. 


Bound service program name. The name of the service program bound to this service program. 


Bound service program signature. The current signature of the service program at the time the service 
program was bound to this service program. 


Close SQL cursor. Specifies when SQL cursors are implicitly closed and SQL-prepared statements are 
implicitly discarded. The possible values are: 


*ENDMOD When the module ends. 
*ENDACTGRP When the activation group is deleted. 


Blank The module does not contain SQL statements. 


Commitment control. The level of commitment control that was specified on the SQL precompile. The 
possible values are: 


*NONE No commitment control was specified on the SQL precompile. Uncommitted changes in other 
jobs can be seen. 


*CHG Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements are locked until the end of the unit of work (transaction). Updated, 
deleted, and inserted rows (records) are locked until the end of the unit of work. Uncommitted 
changes in other jobs can be seen. 


*CS Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements are locked until the end of the unit of work (transaction). Updated, 
deleted, and inserted rows (records) are locked until the end of the unit of work. A row 
(record) that is selected but not updated is locked until the next row (record) is selected. 
Uncommitted changes in other jobs cannot be seen. 


*ALL Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements are locked until the end of the unit of work (transaction). All rows 
selected, updated, deleted, and inserted are locked until the end of the unit of work. 
Uncommitted changes in other jobs cannot be seen. 


Blank The module does not contain SQL statements. 


Connection method. The method used for establishing remote connections when running distributed 
service programs. 


Special values that can be returned are: 


*RUW Only one connection to a relational database is allowed. Consecutive CONNECT statements 
result in the previous connection being disconnected before a new connection is established. 


*DUW Connections to several relational databases are allowed. Consecutive CONNECT statements to 
additional relational databases do not result in disconnection of previous connects. SET 
CONNECTION can be used to switch between connections. Read-only connections may result. 


Blank The module does not contain SQL statements. 


Copyright. The copyright string included in this service program. 


Creation data. Whether the bound module has all the creation data #*and if that data is observable or 
unobservable. *& The possible values are: 


0 *NO. Not all the creation data is present in the bound module. 
v *YES. The creation data is present in the bound module and all of that data is observable. 


22 *UNOBS. The creation data is present in the bound module but not all of that data is observable. 


Copyright length. The length of the copyright string. 
Data item CCSID. The coded character set identifier (CCSID) of this data item. 


Data item export name. Data items that are exported to an activation group. These data items can be used 
outside of the module or service program that they are defined in. 


Data item export name CCSID. The coded character set identifier (CCSID) for the name of this data item 
export. 


Data item export name length. The length of the name of the data export item. 


Data item import name. The name of the data item imports that were resolved by weak exports that had 
been exported to the activation group. 


Data item import name CCSID. The coded character set identifier (CCSID) for the name of this data item 
import. 


Data item import name length. The length of the name of the data import item. 
Data item name. Service program data items that are allowed to be exported. 
Data item name length. The length of the data item name. 
Date format. The format used when accessing date-result columns through SQL. All output date fields are 
returned in this format. For input date strings, the value you specify is used to determine whether the date is 
a valid format. The values returned are: 

*USA USA format (mm/dd/yyyy). 

*[SO International Standards Organization format (yyyy-mm-dd). 

*EUR European format (dd.mm.yyyy). 

*JTS Japanese Industrial Standard Christian Era (yvyyy-mm-dd). 

*MDY Month/day/year format (mm/dd/yy). 

*DMY _ Day/month/year format (dd/mm/yy). 

*YMD_ Year/month/day format (yy/mm/dd). 

*JUL Julian format (a numeric value from 1 to 365). 


Blank The module does not contain SQL statements. 


Date separator. The separator used when accessing date-result columns. This information is blank if the 
module does not contain SQL statements. However, the number of SQL statements field should be checked 
to determine if the module contains SQL statements. This is because a blank may be specified as a 
separator value. 


Debug data. Whether debug data was generated when this module was created. If debug data exists, the 
module may be debugged using the source debugger. The possible values are: 


*YES Debug data was generated. 


*NO Debug data was not generated. 


Default collection name. The collection name used for the unqualified names of tables, views, indexes, 
and SQL packages. Possible values are: 


*NONE There is no default collection name. 


Blank The module does not contain SQL statements. 


Delay PREPARE. Whether SQL prepare processing can be delayed until the statement is actually used. 
The possible values are: 


*YES Prepare processing can be delayed. 


*NO Prepare processing cannot be delayed. 


Blank The module does not contain SQL statements. 


Dynamic user profile. The user profile used for dynamic SQL statements. The following special values 
can be returned: 


*USER Local dynamic SQL statements are run under the profile of the module's user. Distributed 
dynamic SQL statements are run under the profile of the SQL package's user. 


*OWNER Local dynamic SQL statements are run under the profile of the module's owner. Distributed 
dynamic SQL statements are run under the profile of the SQL package's owner. 


Blank The module does not contain SQL statements. 


Enable performance collection. The level of performance collection enabled for this module. The 
following values can be returned: 


‘00'X *NONE or '10'X *PEP This gives the entry/exit information for the PEP only. No entry/exit 
hooks in the module's internal procedures and no precall or postcall 
hooks around calls to other procedures are included. 


Note: If *NONE is shown and the module was created or re-created 
on an iSeries server running Version 3 Release 6 Modification 0 prior 
to the installation of PTF MF11968, the module will not have any 
performance collection enabled. To enable performance collection, 
use one of the following commands and specify 
ENBFPRCOL(*PEP): 


e Change Module (CHGMOD) 
e Change Program (CHGPGM) 
e Change Service Program (CHGSRVPGM) 


'50'X *ENTRYEXIT *NONLEAF This gives the entry/exit information on all of the non-leaf procedures 
in the module. This includes the PEP routine. This is useful to capture 
information on most routines but not at the expense of destroying the 
‘leaf-ness' of the leaf procedures. 


'70'X *ENTRYEXIT *ALLPRC This gives the entry/exit information on all the procedures of the 
module (including those that were leaf procedures). This includes the 
PEP routine. This is useful to capture information on all procedures. 


'‘DO'X *FULL *NONLEAF This gives the entry/exit information on all the procedures of the 
module that are not leaf procedures. This includes the PEP routine. 
Precall and postcall hooks around calls to external procedures are also 
included. 


'FO'X *FULL *ALLPRC This gives the entry/exit information on all procedures of the module 
(including those that were leaf procedures). This includes the PEP 
routine. Precall and postcall hooks around calls to external procedures 
are also included. This is useful to capture information on all 
procedures. 


Format name specified. The format name that was passed to this API on the call in the format parameter. 


Language identifier. Returns the 3-character language identifier used when the module was compiled. The 


following special values can also be returned: 


*JOBRUN The language identifier associated with the job at the time the service program into which 
the module is bound runs. 


Blank The module does not contain any language identification information. 


Length of Licensed Internal Code options. The size, in two-byte characters, of the Licensed Internal 
Code options string. This will be 0 if no Licensed Internal Code options were used for this module. 


Length of long procedure export name. The actual size, in bytes, of the long procedure export name for 
this entry. 


Licensed Internal Code options. The Licensed Internal Code options that are in use by the module. This 
field is specified in UCS-2 (CCSID 13488). 


Licensed program. If the module was part of a licensed program at bind time, this field shows the product 
number and the level of the licensed program. This is blank if the module is not part of a licensed program 
at bind time. 


Long procedure export CCSID. The coded character set identifier (CCSID) of this procedure export 
name. 


Long procedure export name. Service program procedures that are allowed to be exported. 


Maximum optimization level. The highest level of optimization this module could have at bind time. If 
observability has been removed from the module, this maximum optimization level value might not be the 
same as the one specified at module creation. The possible values are: 


65535 The module is not restricted to a maximum optimization level. It can be retranslated to any of 
the supported optimization levels. 65535 is also known as *NOMAX. 


40 Maximum level of optimization. This level includes all the optimizations performed at 
optimization level 30. In addition, it includes optimization that disables call and instruction 
tracing. Thus, tracing of modules created at this optimization level cannot be done. 


30 More optimization is performed in addition to those performed at optimization level 20. 
Variables cannot be changed but can be displayed while the program is being debugged. 
However, the displayed value of the variable during debugging may not be its actual value. 30 is 
also known as *FULL. 


20 Some optimization is performed on the generated code. When the module optimized at this level 
is being debugged, the variables can be displayed but not changed. This level improves the 
performance of the module slightly over level 10. 20 is also known as *BASIC. 


10 No additional optimization is performed on the generated code. Variables can be displayed and 
changed when the program is being debugged. With no optimization of the code, this value 
provides the lowest level of module performance. 10 is also known as *NONE. 


Module attribute. The language in which the module is written. This field can be blank (for example, a 
module created by a compilation process internal to IBM). 


Module CCSID. The coded character set identifier (CCSID) for this module. 


Module creation date and time. The date and time the module was created. The creation date and time 
field is in the CY YMMDDHHMMSS format as follows: 


C Century, where 0 indicates years 19xx and 1 indicates years 20xx. 


YY Year 


MM Month 
DD Day 
HH Hour 
MM Minute 
SS Second 


Naming convention. The convention used for naming objects in SQL statements. The possible values are: 
*SQL The SQL naming convention is used. 
*SYS The system naming convention is used. 


Blank The module does not contain SQL statements. 


Number of procedures. The number of procedures defined in the module. This number includes the 
program entry procedure (PEP), if one was generated by the compiler for this module. 


Number of procedures block-order measured. The number of procedures defined in the module that had 
block-order profiling data collected at the time block-order profiling data was applied. If the module does 
not have block-order profiling data applied, this value will be zero. 


Number of procedures block reordered. The number of procedures defined in the module that are block 
reordered. If the module does not have block-order profiling data applied, this value will be zero. This value 
can decrease if the service program in which this bound module is contained is retranslated. 


Number of SQL statements. The number of SQL statements contained in the module. This value is zero if 
the module does not contain SQL statements. 


Object control level. The object control level for the module at the time it was bound into this service 
program. You can compare the object control level of a module to the object control level of a listing to 
make sure they match. 


Offset to Licensed Internal Code options. The offset from the beginning of the user space where the 
Licensed Internal Code options begin. This will be 0 if no Licensed Internal Code options were used for 
this module. 


Offset to long procedure export name. The offset from the beginning of the user space where this 
procedure export name is stored. 


Optimization level. Optimization levels cause the translator to produce machine code that reduces the 
amount of system resources necessary to run the program. The more optimization, the more efficiently the 
module runs on the system. Also, with more optimization you may not be able to change or view variables 
that have been optimized. The possible values are: 


65535 The module is not restricted to a maximum optimization level. It can be retranslated to any of 
the supported optimization levels. 65535 is also known as *NOMAX. 


40 Maximum level of optimization. This level includes all the optimizations performed at 
optimization level 30. In addition, it includes optimization that disables call and instruction 
tracing. Thus, tracing of modules created at this optimization level cannot be done. 


30 More optimization is performed in addition to those performed at optimization level 20. 
Variables cannot be changed but can be displayed while the program is being debugged. 
However, the displayed value of the variable during debugging may not be its actual value. 30 is 
also known as *FULL. 


20 Some optimization is performed on the generated code. When the module optimized at this level 
is being debugged, the variables can be displayed but not changed. This level improves the 
performance of the module slightly over level 10. 20 is also known as *BASIC. 


10 No additional optimization is performed on the generated code. Variables can be displayed and 
changed when the program is being debugged. With no optimization of the code, this value 
provides the lowest level of module performance. 10 is also known as *NONE. 


Procedure export name. Service program procedures that are allowed to be exported. 
Procedure export CCSID. The coded character set identifier (CCSID) of this procedure name export. 
Procedure export name length. The length of the procedure export name. 


Profiling data. The profiling data attribute for the module that is bound into this service program. Possible 
values follow: 


*NOCOL The collection of profiling data is not enabled and block-order profiling data is not 
applied to the module bound into this service program. 


*COL The collection of profiling data is enabled. Any block-order profiling data that was 
applied has been removed for the module bound into this service program. 


*APYBLKORD  Block-order profiling data is applied to the module that is bound into this service 
program. See the number of procedures block reordered field for the current number of 
procedures in this module that are block reordered. 


PTF number. The program temporary fix (PTF) that resulted in the creation of the module. This field is 
blank for user-created modules. 


Reason code. The reason code describing why the returned list is only a subset. The following values can 
be returned: 


0000 The list returned in the user space contains all information meeting the search criteria. 


0001 Additional procedure exports were found that meet the search criteria but could not be included 
in the returned list. The requested format could not handle procedure names greater than 256 
characters. Call the API again specifying the SPGL0610 format to get all the available 
information. 


Relational database. The default relational database that was specified on the SQL precompile. A 
nonblank value other than *LOCAL specifies the name of the relational database to be resolved through the 
relational database directory. The following special values can be returned: 


*LOCAL The module can only access data on the local system. 


Blank The module does not contain SQL statements. 


Release module created for. The version, release, and modification level of the operating system for 
which the module was created. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr — The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


Release module created on. The version, release, and modification level of the operating system on which 
the module was created. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr The character R is followed by a 1-character release level. 


Mm __ The character M is followed by a 1-character modification level. 


Reserved. An ignored field. 
Service program library name. The name of the library containing the service program. 


Service program library name specified. The service program library name that was passed to this API 
on the call in the qualified service program name parameter. 


Service program name. The name of the service program. 


Service program name specified. The service program name that was passed to this API on the call in the 
qualified service program name parameter. 


Signature. A valid signature of this service program. 
Size of data item export. The size, in bytes, of the data item export. 
Size of this entry. The size, in bytes, of this entry. 


Sort sequence table library name. The name of the library that contained the sort sequence table used 
when the module was compiled. This does not apply to SQL statements in the module. This information is 
blank if the module does not contain any sort sequence information or a special value was returned for the 
sort sequence table name. The following special values can be returned: 


*LIBL The sort sequence table is found in the library list when the service program runs this 
module. 


*CURLIB The sort sequence table is found in the current library when the service program runs this 
module. 


Sort sequence table name. The name of the sort sequence table used when the module was compiled. This 
does not apply to SQL statements in the module. The following special values can be returned: 


*HEX No sort sequence is used. 


*JOBRUN The sort sequence value associated with the job at the time the service program runs 
this module is used. 


*LANGIDSHR _ The shared sort sequence for the language identifier is used. 


*LANGIDUNQ The unique sort sequence for the language identifier is used. 


Note: This sort sequence table does not apply to SQL statements. 


Source file library name. The name of the library that contains the source file used to create the module. 
The field is blank if no source file was used to create the module. 


Source file member name. The name of the member in the source file. The field is blank if no source file 
was used to create the module. 


Source file name. The name of the source file used to create the module. The field is blank if no source file 
was used to create the module. 


Source file updated date and time. The date and time the member in the source file was last updated. The 
field is in the same format as the module creation date and time field. The field is blank if no source file 
was used to create the module. 


SQL language identifier. The 3-character language identifier used when the module was compiled. This 
information is blank if the module does not contain any language identification information. The following 
possible special value can be returned: 


*JOBRUN _ The language identifier is the LANGID associated with the job at the time the module is 
run. 
SQL package library name. The name of the library the SQL package is in. 


SQL package name. The name of the SQL package created on the relational database specified on the 
RDB parameter of the command that created this module. Possible values are: 


*NONE This is not a distributed module. 

Blank The module does not contain SQL statements. 
SQL path. The list of libraries used during resolution of functions and data types within SQL statements. 
The list is in the form of repeating library names, each surrounded by double quotes and separated by 


commas. Even though 3483 bytes are reserved, the path's length is determined by the SQL path length 
entry. 


SQL path length. The length, in bytes, of the SQL path. 


SQL sort sequence table library name. The name of the library that is used to locate the SQL sort 
sequence table. This information is blank if the module does not contain any SQL sort sequence 
information or a special value was returned for the SQL sort sequence table name. The following special 
values can be returned: 


*LIBL The SQL sort sequence table is found by looking in the library list. 
*CURLIB The SQL sort sequence table is found by looking in the current library. 
SQL sort sequence table name. The sort sequence table name used when the module was compiled. This 


information is blank if the module does not contain any SQL sort sequence information. The following 
special values can be returned: 


*HEX No SQL sort sequence is used for the SQL statements. 


*JOBRUN The SQL sort sequence is the SRTSEQ value associated with the job at the time the 
SQL statements within the module are run. 


*LANGIDSHR _ The shared SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


*LANGIDUNQ _ The unique SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


Storage model. Where the automatic and static storage for this bound module is allocated at run time. The 
following values can be returned: 


0 *SNGLVL Automatic and static storage are allocated from single-level storage. 
1 *TERASPACE Automatic and static storage are allocated from teraspace. 


2 *INHERIT Automatic and static storage are allocated from either single-level storage or 
teraspace, depending on the activation. 


Teraspace storage enabled. The teraspace storage capability for this bound module. Possible values are: 
‘00'X *NO The module bound to this service program is not teraspace storage enabled. 


'80'X *YES The module bound to this service program is teraspace storage enabled. 


Time format. The format used when accessing time-result columns through SQL. All output time fields are 
returned in this format. The values returned are: 


*USA USA format (hh:mm a.m. or p.m.). 

*ISO International Standards Organization format (hh.mm.ss). 
*EUR European format (hh.mm.ss). 

*JIS Japanese Industrial Standard Christian Era (hh.mm.ss). 
*HMS  Hours/minutes/seconds format (hh:mm:ss). 


Blank The module does not contain SQL statements. 


Time separator. The separator used when accessing time-result columns. This information is blank if the 
module does not contain SQL statements. However, the number of SQL statements field should be checked 
to determine if the module contains SQL statements. This is because a blank may be specified as a 
separator value. 


User-modified. Whether the module was changed by the user. The possible values are: 
0 The user did not change the module. 


I The user changed the module. 


User space library name specified. The user space library name that was passed to this API on the call in 
the qualified user space name parameter. 


User space library name used. The name of the library that contains the user space that receives the 
service program information requested. 


User space name specified. The user space name that was passed to this API on the call in the qualified 
user space name parameter. 


User space name used. The name of the user space that receives the service program information 
requested. 


Uses argument optimization (ARGOPT). Whether or not the service program export uses argument 
optimization. The possible values are: 


*YES The service program export uses argument optimization. 


*NO _ The service program export does not use argument optimization. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C20 E Error found by program &1. 

CPF3C21 E Format name &1 is not valid. 

CPF3C90 E Literal value cannot be changed. 

CPF3CAA E List is too large for user space &1. 

CPF3CF1 E Error code parameter not valid. 

CPF5CF6 E Program name &1 not valid special value. 
CPF811A E User space &4 in &9 damaged. 

CPF9570 E Error occurred creating or accessing debug data. 
CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 

CPF9803 E Cannot allocate object &2 in library &3. 
CPF9804 E Object &2 in library &3 damaged. 

CPF9806 E Cannot perform function for object &2 in library &3. 
CPF9807 E One or more libraries in library list deleted. 
CPF9808 E Cannot allocate one or more libraries on library list. 
CPF9810 E Library &1 not found. 

CPF9820 E Not authorized to use library &1. 

CPF9830 E Cannot assign library &1. 

CPF9838 E User profile storage limit exceeded. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
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Process Commands (QCAPCMD) API 


Required Parameter Group: 


Source command string Input Char(*) 
Length of source command string Input Binary(4) 
Options control block Input Char(*) 
Options control block length Input Binary(4) 
Options control block format Input Char(8) 
Changed command string Output Char(*) 


Length available for changed command Input Binary(4) 
string 

Length of changed command string Output Binary(4) 
available to return 


Error Code 1/0 Char(**) 


Default Public Authority: “EXCLUDE 


Threadsafe: Yes. See Usage Notes for command considerations. 


The Process Commands (QCAPCMD) API is used to perform command analyzer processing on command 
strings. You can check or run CL commands from HLLs as well as check syntax for specific source 
definition types. 
You can use the QCAPCMD API to: 

e Check the syntax of a command string prior to running it 

e Prompt the command and receive the changed command string 


e Run acommand from an HLL 


Authorities and Locks 


Command 
*USE 
Command library 
*EXCLUDE 


Required Parameter Group 


Source command string 
INPUT; CHAR(*) 


The command string to be prompted for or run. 


Length of source command string 
INPUT; BINARY(4) 
The length of the source command string. Valid values are between 1 and 32 702. Message 
CPF3C1D will result for values outside this range. This length can include trailing blanks. 
Options control block 
INPUT; CHAR(*) 


The options that control the handling of the command string. The layout of this parameter is the 
CPOPO0100 Format. 


Options control block length 
INPUT; BINARY(4) 
The length of the options control block. A minimum length of 20 is required for the CPOPO100 
format. 
Options control block format 
INPUT; CHAR(8) 


The format of the options control block. CPOPO100 is the only valid value. For more information, 
see CPOP0100 Format. 


Changed command string 
OUTPUT; CHAR(*) 


The rebuilt command string. This is the updated command string, which includes changes from 
prompting, ordering of parameters, and the addition of keywords. This string may be substantially 
longer than the source command string. If an error occurs that prevents the command string from 
being rebuilt, this field is not changed. No padding is performed on the value returned. The length 
of changed command string available to return parameter should be used to determine how much 
data is returned. 


Length available for changed command string 
INPUT; BINARY(4) 
The length available to return the updated command string. If an updated command string is not 
desired, a special value of 0 may be specified. This value must be a positive number or zero. 
Length of changed command string available to return 
OUTPUT; BINARY(4) 
The length of the changed command string returned or available to return. If zero is specified for 
the length available for changed command string parameter, this value is not set. If an error occurs 
that prevents the command string from being rebuilt, this field is zero. If the changed command 


string parameter is not large enough to hold the entire rebuilt command string, this value is the total 
length available. The changed command string is truncated. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


CPOP0100 Format 


The CPOP0100 format includes information on the contents of the options control block parameter. The 
following table shows how this information is organized. For detailed descriptions of the fields in the list, 


see Field Descriptions. 


| Offset 
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Field Descriptions 


Command string syntax. Whether command processing should be done in OS/400 mode or System/38 
mode. The possible values are: 


0 Use system syntax. The specification of qualified objects is in the format library/object. 


I Use System/38 syntax. The specification of qualified objects is in the format object.library. The 
system searches the QUSER38 library (if it exists) and the QSYS38 library for the command even 
though these libraries are not in the library list. 


DBCS data handling. Whether the command analyzer should handle the SO/SI characters as DBCS 
delimiters. It is valid with all classes of command processing. This option is the equivalent of specifying the 
IGC process control parameter on the Execute Command (QCMDEXC) and Check Command Syntax 
(QCMDCHK) APIs. The possible values are: 


0 Ignore DBCS data. 
I Handle DBCS data. 


Message retrieve key. The message retrieve key identifies a request message. If prompting is requested, 
the request message identified by the message retrieve key is replaced by the updated command string. The 
updated command can then be logged in the job log. If the message key contains all hexadecimal zeros or 
all blanks, no request message is updated. The message key is valid for processing command types 0, 1, 2, 
and 3. The message key is ignored for processing command types 4, 5, 6, 7, 8, and 9. The message key is 
valid only during the current job. 


Prompter action. Indicates whether the prompter should be called on a command string. 


O Never prompt the command. This will prevent a command prompt even if selective prompting 
characters are present in the command string. 


Note: When the type of command processing field is 2 or 3 and there are missing required 
parameters, the command will be prompted, even when the prompter action is set to 0. 


Always prompt the command. This forces a command prompt even if selective prompting characters 
are not present in the command string. 


Prompt the command if selective prompting characters are present in the command string. A 
CPEFO0008 exception is sent if this value is specified with types of command processing values 4 
through 8. 


Show help. Provides help display for the command. 


Reserved. This area must be set to hexadecimal zeros. 


Type of command processing. The type of command processing to be performed by the system. The 
following processes can occur: 


0 


Command running. The processing for this type is the same as that performed by the QCMDEXC 
API. Commands processed must have a value of “EXEC on the ALLOW parameter of the Create 
Command (CRTCMD) or the Change Command (CHGCMD) command. 


Command syntax check. The processing for this type is the same as that performed by the 
QCMDCHK API. 


Command line running. This processing is like that provided by the QCMDEXC API but with the 
following additions: 


e Limited user checking is performed. 
e Prompting for missing required parameters is performed. 


e Ifthe System/36 environment is active and the commands are System/36 commands, the 
System/36 environment runs the commands. 


This type processes commands with entry codes of Job: I (value of *INTERACT on the ALLOW 
parameter of the CRTCMD or CHGCMD command). While this type is meant to implement an 
interactive command line, it can be used in batch. When used in a batch job, the entry code for the 
command must be Job: B. Limited user checking and System/36 environment processing is done 
while prompting options are ignored. 


Command line syntax check. This processing provides the check only complement of type 2 
(command line running). The check option performs all checks against CL rules. The System/36 
environment is not called. 


CL program statement. The command string is checked according to the rules for CL programs 
(source entry utility (SEU) member type of CLP). Commands may not be run with this type. 
Command prompts include a prompt for a command label and comment. Variable names are 
allowed. Commands processed for this type must be defined with entry codes of Pgm: B, Pgm: I, or 
Pgm: B,I. They have values of *BPGM or *IPGM on the ALLOW parameter of the CRTCMD or 
CHGCMD command. 


CL input stream. The command string is checked according to the rules for CL batch jobs (SEU 
member type of CL). Commands may not be run. Command prompts include a prompt for 
comment. Variable names are not allowed. 


Command definition statements. The command string is checked according to the rules for 
command definition (SEU member type of CMD). Commands may not be run. The commands are 
restricted to CMD, PARM, ELEM, QUAL, DEP, and PMTCTL. 


Binder definition statements. The command string is checked according to the rules for binder 
definition (SEU member type of BND). Commands may not be run. The commands are restricted to 
STRPGMEXP, ENDPGMEXP, and EXPORT. 


S User-defined option. This option allows a user to create user-defined option command strings 
similar to those used by the programming development manager (PDM). It allows checking and 
creating a command string for future use with types 0 through 3 except that variables are allowed. 
The command string produced may not be directly operable. That is, if CL variables were specified 
in the command string, the user must perform a substitution prior to using the API with types of 0 or 
2; 


9  YLECL program source. The source is checked according to the rules for ILE CL programs (source 
entry utility (SEU) member type of CLLE). Commands may not be run with this type. Command 
prompts include a prompt for a command label and comment. Variable names are allowed. 
Commands processed for this type must be defined with entry codes of CLLE: B, CLLE: I, or 
CLLE: B,I. They have values of *IMOD or *BMOD on the ALLOW parameter of the CRTCMD or 
CHGCMD command. 


10 Command prompt string. The command analyzer prepares the source command for prompting and 
returns the command string to use for the initial prompt display. If the command has an exit 
program registered for the QIBM_QCA_CHG_COMMAND exit point, the exit program is called. 
If the exit program replaces the original command, the changed command string returned by 
QCAPCMD is the replacement command from the exit program. The returned command string may 
not be syntactically correct because no syntax checking is done on the replacement command. The 
length of changed command string available to return is set to 0 and the changed command string 
parameter is not changed if any of these conditions are true: 


1. The exit program is not called 
2. The exit program ends in error. 


3. The exit program does not replace the command. 


Usage Notes 


1. While this API is threadsafe, it should not be used to run a command that is not threadsafe in a job 
that has multiple threads. Use the Display Command (DSPCMD) command to determine whether a 
command is threadsafe. 


2. The prompt actions controlled by the prompter option field in the option control block have the 
following considerations. 


o For commands with a value of 0, 1, 2, or 3 for the type of command processing field, a 
prompt occurs when 2 is specified for the prompter option field if: 


m Selective prompting is specified in the source command string parameter. 
mu The job is running interactively. 


o. If this API is called in a batch job with a valid prompt request, it is ignored. A valid prompt 
request is issued by specifying: 


m 1 for the prompter option field 


m 2 for the prompter option field with selective prompting characters in the command 
string 


m 3 for help 


3. Calls of the API in batch jobs with values of 4, 5, 6, or 7 for the type of command processing field 
are processed. However, prompting requests are ignored. 


4. The prompter option field in the options control block is ignored if 10 is specified for the type of 
command processing field. 


Error Messages 


Message ID 
CPF0008 E 

CPF24B4 E 
CPF3CIDE 
CPF3C20 E 
CPF3C90 E 
CPF3CF1 E 
CPF3CF2 E 
CPF9872 E 


xxxnnnn E 


Error Message Text 

Value in option control block not valid. 

Severe error while addressing parameter list. 

Length specified in parameter &1 not valid. 

Error found by program &1. 

Literal value cannot be changed. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 

Program or service program &1 in library &2 ended. Reason code &3. 

Any escape message issued by any command may be returned. The messages listed 


previously are those issued by this API. Once the API has called the command 
analyzer, any message issued as an escape may appear. 


API introduced: V2R3 


Top | Program and CL Command APIs | APIs by category 


Replace Command Exit Program (QCARPLCM) 
API 


Required Parameter Group: 


Change command exit Input Char(*) 
information 


Replacement command Output Char(*) 


Length of replacement Output Binary(4) 
command string 


Default Public Authority: *USE 


Threadsafe: Yes 


The Replace Command Exit Program (QCARPLCM) API may be used as the exit program for the 
QIBM_QCA_CHG_COMMAND for any command. If the original command was library-qualified with 
*SYSTEM or *NLVLIBL, the library qualifier will be replaced with *LIBL. None of the parameter values 
specified on the original command will be changed. See the Command Analyzer Change exit program for a 


description of the QIBM_QCA_CHG_COMMAND exit point. 


Authorities and Locks 


None 


Required Parameter Group 


Change command exit information 
INPUT; CHAR(*) 


Information about the command that the command analyzer was called to process. See Format 
CHGCO0100 in the Command Analyzer Change exit program. 


Replacement command 
OUTPUT; CHAR(*) 


A string containing the command string that is to be substituted for the one that the command 
analyzer was called to process. If the original command was library-qualified with *SYSTEM or 
*NLVLIBL, the library qualifer will be replaced with *LIBL. None of the parameter values 
specified on the original command will be changed. The maximum length of the changed command 
string is 32000 bytes. 


Length of replacement command string 
OUTPUT; BINARY(4) 


The length of the replacement command string (0 - 32000) in bytes. 


Usage Notes 


Registration considerations 


Use the Add Exit Program command (ADDEXITPGM) or API (QUSADDEP, QusAddExitProgram) to 
register this program as an exit program for a command. You must specify 20 bytes of exit program data. 
The first 10 characters specify the command name; the second 10 characters specify the library name. For 
example, to register QCARPLCM as the exit program to be called at the QIBM_QCA_CHG_COMMAND 
exit point for the Display Job (DSPJOB) command in library QSYS, specify: 


ADDEXITPGM EXITPNT (QIBM_OCA_CHG_COMMAND) 
FORMAT (CHGC0100) 
PGMNBR (* LOW) 
PGMDTA(*JOB 20 'DSPJOB QSYS ') 


If you register QCARPLC®M as an exit program for a command in library QSYS, it also will be called for 
commands in the secondary language libraries. For example, if the exit program is registered for the 
DSPJOB command in library QSYS, it also will be called for the DSPJOB command in library QSYS2962. 


If you rename the command or the library or move the command to another library, you also must have the 
exit program registered using the new command and library names. 


If you register QCARPLC®M as the exit program for a command, you cannot register another exit program 
for the command for the QIBM_QCA_CHG_COMMAND exit point. 


Runtime considerations 


If two applications on the same system need to replace the same command with one of the same name but 
in different libraries, they can register QCARPLCM as the exit program for the 
QIBM_QCA_CHG_COMMAND exit point for the command. The applications must ensure that the correct 
application library is at the beginning of the system part of the library list. 


If the original command was library-qualified with a specific library name, the exit program will not be 
allowed to change the command string, so the command analyzer will search only the specified library for 
the command. 
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Retrieve Associated Space 
(QbnRetrieveAssociatedSpace) API 


Required Parameter Group: 


Qualified user space name Char(20) 
Call level Binary(4) 
Associated space identifier Char(10) 
Error code Char(*) 


Default Public Authority: *USE 


Service Program: QBNPREPR 


Threadsafe: No 


The Retrieve Associated Space (QbnRetrieveAssociatedSpace) API is used by a run-time routine to retrieve 
data stored with the QbnAddAssociatedSpaceEntry API. This data will be placed into the specified user 
space. The format of the data is specified by the user when placed into the associated space of a module 
using the QbnAddAssociatedSpaceEntry API. This API should be called only by a preprocessor run-time 
routine. 


Authorities and Locks 


User Space Authority 
*CHANGE 

User Space Library Authority 
*USE 

ILE Program or Service Program Authority 
*EXECUTE 


Required Parameter Group 
Qualified user space name 
INPUT; CHAR(20) 


The qualified name of the user space that is to receive the associated space data. The first 10 
characters contain the user space name. It is left-justified and padded with blanks. The second 10 
characters contain the name of the library where the user space is located. It is left-justified and 
padded with blanks. The library name can be specified with the following special values: 


*CURLIB The job's current library 


*LIBL The library list 


Call level 
INPUT; BINARY(4) 


The call level parameter identifies the location in the call stack of the ILE program or service 
program, which contains the associated space data. 


0 The current program in the call stack identifies the associated space of the ILE program or 
service program. 


n The nth caller up the stack identifies the associated space of the ILE program or service 
program. This is a positive number. 


Associated space identifier 
INPUT; CHAR(10) 


The associated space identifier has the following special value: 


*PREPROC The type of data from within the associated space to copy into the user space. The 
special value must be left-justified and padded with blanks. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 

CPF2207 E Not authorized to use object &1 in library &3 type *&2. 
CPF24B4 E Severe error while addressing parameter list. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF5CA2 E &1 is not a valid associated space identifier parameter. 
CPF5CA4 E Error occurred while addressing API Parameter. 
CPF5D24 E Unexpected error occurred during preprocessor processing. 
CPF811A E User space &4 in &9 damaged. 

CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 


CPF9803 E 
CPF9807 E 
CPF9808 E 
CPF9810 E 
CPF9820 E 
CPF9830 E 
CPF9838 E 
CPF9872 E 


Cannot allocate object &2 in library &3. 

One or more libraries in library list deleted. 

Cannot allocate one or more libraries on library list. 
Library &1 not found. 

Not authorized to use library &1. 

Cannot assign library &1. 

User profile storage limit exceeded. 


Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V3R1 


Top | Program and CL Command APIs | APIs by category 


Retrieve Command Definition (QODRCMDD) 
API 


Required Parameter Group: 


Qualified user index name Char(20) 
Destination Char(*) 
Destination format name Char(8) 
Receiver variable Char(*) 
Receiver format name Char(8) 
Error Code Char(*) 


Default Public Authority: *USE 


Threadsafe: Yes 


The Retrieve Command Definition (QCDRCMDD) API retrieves the command definition source for a 
given command in XML tag language format. The source is returned in the destination provided in UTF-8 
(CCSID 1208). See the Document Type Definition (DTD) in /QIBM/XML/DTD/QcdCLCmd.dtd for 
details of the XML tag language returned by this API. 


Authorities and Locks 


API Public Authority 
*USE 
Command Library Authority 
*EXECUTE 
Command Authority 
*USE 
Command Lock 
*SHRNUP 
Output File Authority 


Authority to the path and file are determined by the open() API. For details, see the Authorities 
section of the open()--Open File API for files opened with an access mode of O_WRONLY and 


O_TRUNC. 
Output File Lock 
*SHRNUP 


Required Parameter Group 
Qualified command name 
INPUT; CHAR(20) 


The library-qualified command name for which to retrieve the command definition source. The first 
10 characters contain the command name, while the second 10 characters identify the library name. 
The following special values are supported for the library name: 


*CURLIB The job's current library 


*LIBL The library list 


Destination 
INPUT; CHAR(*) 


The destination for the XML source. This can be either the receiver variable or the output file path 
name. This parameter must be coded to the specification of the destination format. 


*CURLIB The job's current library 


*LIBL The library list 


Destination format name 
INPUT; CHAR(8) 


The destination format to determine where the XML source will be stored. Possible values are: 
DESTO100 Return the XML source in the receiver variable. 


DEST0200_ Return the XML source in the output file path coded in the destination parameter. 


Receiver variable 
OUTPUT; CHAR(*) 
The variable that is to receive the XML source requested. The variable is used only when the 


destination format is DESTO100. If the receiver variable is not large enough to hold the entire 
source, no partial source is returned. 


Receiver format name 
INPUT; CHAR(8) 


The format of the command definition to be returned. You must use the following format name: 


CMDDO100 XML source is returned. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. 


DEST0100 Format 


The following information needs to be supplied for the DEST0100 format. 


| Offset 
[Dec Hex Type Field 


| 0 0 BINARY(4) Length of receiver variable 


Field Descriptions 


Length of receiver variable. The length of the receiver variable. If the length is larger than the size of the 
receiver variable, the results may not be predictable. The minimum length is 8 bytes. 


DEST0200 Format 


The file path name where the XML source is returned. See Path name format for information on the file 
path name. 


CMDD0100 Format 


The following information is returned for the CMDD0100 format. 


| Offset 
[Dec Hex Type Field 


| 0 0 BINARY(4) Bytes returned 
| 4 4 BINARY(4) Bytes available 
| 8 8 BINARY(4) XML Source Data 


Field Descriptions 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 
XML source data. The XML source for the command. If the receiver variable is not large enough to hold 


the entire XML source or if an unexpected error occurs while writing to the receiver variable, no data will 
be returned. 


Usage Notes 


The output file path name is represented by the 'Path name' field in the 'Path Name Format’ structure when 
using the DEST0200 destination format. The output file path name is used to store the XML source. The 
target of the output file path name is referred to as the output file. The output file is opened for writing only, 
in text only mode, in CCSID 1208, and allows sharing with readers only. If the output file exists, the file is 
truncated to zero length before writing any data. The existing output file should have been created with a 
CCSID of 1208; otherwise, the resulting XML output may not be usable. If the output file does not exist, it 
will be created with a CCSID of 1208 before attempting to write the XML source to it. The output file is 
created so that the file owner has read and write permission to it. The output file can be replaced if the user 


has the authority to do so. For more information on authority requirements for files, see the open(Q)--Open 
File API in the Integrated File System section of the OS/400 APIs in the Information Center. 


If the CCSID of the command is 65535, the API uses the job default CCSID as the CCSID for the 


command. 


Error Messages 


Message ID Error Message Text 

CPE3006 E Input/output error. 

CPE3014 E The object name is not correct. 

CPE3021 E The value specified for the argument is not correct. 
CPE3025 E No such path or directory. 

CPE3027 E Operation not permitted. 

CPE3029 E Resource busy. 

CPE3401 E Permission denied. 

CPE3403 E Not a directory. 

CPE3404 E No space available. 

CPE3406 E Operation would have caused the process to be suspended. 
CPE3407 E Interrupted function call. 

CPE3408 E The address used for an argument was not correct. 
CPE3436 E There is not enough buffer space for the requested operation. 
CPE3440 E Operation not supported. 

CPE3450 E Descriptor not valid. 

CPE3452 E Too many open files for this process. 

CPE3453 E Too many open files in the system. 

CPE3460 E Storage allocation request failed. 


CPE3470 E 
CPE3471 E 
CPE3474 E 
CPE3484 E 
CPE3485 E 
CPE3486 E 
CPE3489 E 
CPE3490 E 
CPE3499 E 
CPE3500 E 
CPE3507 E 
CPE3511 E 
CPE3512 E 
CPE3513 E 
CPE3524 E 
CPF24B4 E 
CPF3C19 E 
CPF3C21 E 
CPF3C24 E 
CPF3C90 E 
CPF3CF1 E 
CPF3CF2 E 
CPF9801 E 
CPF9802 E 
CPF9803 E 
CPF9810 E 
CPF9820 E 
CPF9830 E 
CPF9872 E 


Function not implemented. 
Specified target is a directory. 
Unknown system state. 

A damaged object was encountered. 
A loop exists in the symbolic links. 
A path name is too long. 

System resources not available to complete request. 
Conversion error. 

Object is suspended. 

Object is a read only object. 

Object too large. 


File ID conversion of a directory failed. 


A File ID could not be assigned when linking an object to directory. 


File handle rejected by server. 

Function not allowed. 

Severe error while addressing parameter list. 
Error occurred with receiver variable specified. 
Format name &1 is not valid. 

Length of the receiver variable is not valid. 
Literal value cannot be changed. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Object &2 in library &3 not found. 

Not authorized to object &2 in &3. 

Cannot allocate object &2 in library &3. 
Library &1 not found. 

Not authorized to use library &1. 


Cannot assign library &1. 


Program or service program &1 in library &2 ended. Reason code &3. 


API introduced: V5R1 


Top | Program and CL Command APIs | APIs by category 


Retrieve Command Information (QODRCMDI) 
API 


Required Parameter Group: 


Receiver variable Char(*) 
Length of receiver variable Binary(4) 


Format name Char(8) 
Qualified command name Char(20) 
Error code Char(*) 


Default Public Authority: *USE 


Threadsafe: Yes 


The Retrieve Command Information (QCDRCMDJ) API retrieves information from a command definition 
object and places it into a single variable in the calling program. The amount of information returned 
depends on the size of the variable. The information returned is the same information returned by the 
Display Command (DSPCMD) command. 


You can use the QCDRCMDI API to retrieve any operable command. This includes both interactive (such 
as Display Program (DSPPGM) and Create Library (CRTLIB)) and non-interactive (such as DO, IF, and 
ELSE) commands. It does not include command definition statements that appear in command source, such 
as CMD, DEP, ELEM, PARM, PARMCTL, and QUAL. 


Authorities and Locks 


Command Definition Object Authority 
*USE 

Library Authority 
*EXECUTE 

Command Definition Object Lock 
*SHRRD 


Required Parameter Group 


Receiver variable 
OUTPUT; CHAR(*) 
The variable that is to receive the information requested. The minimum size for this area is 8 bytes. 


You can specify the size of this area to be smaller than the format requested as long as you specify 
the length parameter correctly. As a result, the API returns only the data that the area can hold. 


Length of receiver variable 
INPUT; BINARY(4) 


The length of the receiver variable. If this value is larger than the actual size of the receiver 
variable, the result may not be predictable. The minimum length is 8 bytes. 


Format name 
INPUT; CHAR(8) 


The format of the command information to be returned. One of the following format names may be 
used: 


CMDIO100 Format Basic command information. 


CMDI0200 Format Complete command information. 


Qualified command name 
INPUT; CHAR(20) 


The name of the command whose values are to be retrieved. The first 10 characters contain the 
name of the command. The second 10 characters contain the name of the library where the 
command is located. 


You can use these special values for the library name: 
*CURLIB The job's current library 


*LIBL The library list 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


CMDI0100 Format 


The following table describes the information that is returned in the receiver variable for the CMDIO100 
format. For detailed descriptions of the fields, see Field Descriptions. 


|  —- Offset 
a c | Type Field 


[335 | 14F  |CHARGS) [Reserved ~~~~SOSC~S~S 


The offsets to these CHAR(*) Help bookshelf information 
fields are specified in 


CMDI0200 Format 


The following table describes the information that is returned in the receiver variable for the CMDI0200 
format. For detailed descriptions of the fields, see Field Descriptions. 


| Offset 
| Dec | Hex |Type Field 


| | | [Returns everything from format CMDI0100 
| 350 | 15E [CHAR(10) [REXX source file name 

| 360 | 168 |CHAR(10) [REXX source file library name 

| 370 172 [CHAR(10) [REXX source file member name 

| 380 | 17C [CHAR(10) [REXX command environment name 

| 390 | 186 |CHAR(10) [REXX command environment library name 
| 400 | 190 [CHAR(40) [Reserved 

| 440 | 1B8 [BIN ARY(4) [N umber of REXX exit entries 

| 444 | 1BC [BINARY(4) [Length of a REXX exit entry 


Format of a REXX exit entry (repeated by the number of REXX exit entries) 


See See |CHAR(10) REXX exit program name 

note note 

See See |CHAR(10) REXX exit program library name 
note note 

See See |BINARY(4) REXX exit code 

note note 


Note: The decimal and hexadecimal offsets to the above 3 fields depend on the 
number of REXX exit entries and the length of a REXX exit entry. The REXX exit 
entry fields (currently REXX exit program name, REXX exit program library name, 
and REXX exit code) repeat, in the order listed, by the number of REXX exit entries 
defined for this command. 


The offsets to CHAR(*) Help bookshelf information 


Help Bookshelf Information 


The following table describes the help bookshelf information that is returned for both the CMDIO100 and 
CMDIO0200 formats. 


| Offset 
| D c | Hex /Type Field 
CHAR(71) CO 
He bay 
CHAR(8) eS <<$——__— bookshelf 
aie ae 


Note: The location and length of the help bookshelf information structure may be 


determined by using the offset to help bookshelf information field and the length of 
help bookshelf information field. 


Field Descriptions 


For more information on the following fields, refer to the documentation for the Create Command 
(CRTCMD) command in the online help. 


Allow limited user. Whether or not a user with limited authorities is allowed to run this command. The 
possible values are 0 (*NO) or 1 (* YES). 


Bytes available. The length of all data available for the requested format. All available data is returned if 
enough space is provided. 


Bytes returned. The length of all data actually returned. If the data is truncated because the receiver 
variable is not large enough to hold the data, this value is less than the bytes available. 


Coded character set ID (CCSID). The value of the coded character set ID associated with this command. 
It is the value of the job coded character set ID when this command was created. 


Command library name. The name of the library in which the command description resides. 
Command name. The name of the command description about which information is being returned. 


Command processing program call state. The state the command processing program is called from. The 
possible values are: 


*S The command processing program is called from system state. 


*U The command processing program is called from user state. 


Command processing program library name. The name of the library in which the process command 
program resides. This field is blank if the command processing program name contains the special value 
*REXX. 


Command processing program name. The name of the program that accepts parameters from the 
command and processes the command. The possible values are: 


*REXX The REXX fields returned in the CMDI0200 format contain valid information 
about the command. 


CPP-program-name The command processing program name. 


Current library. The name of the library used as the current library during the processing of this 
command. The possible values are: 


*NOCHG The current library does not change for the processing of this command. If the current 
library is changed during processing of the command, the change remains in effect after 
command processing is complete. 


*CRTDFT No current library is active during processing of the command. The current library that 
was active before command processing began is restored when processing is completed. 


library-name The name of the library that is used as the current library. When command processing is 
completed, the current library is restored to its previous value. 


Enabled for GUI indicator. Whether the command prompt panels are enabled for conversion to a 
graphical user interface. The possible values are: 


0 The command prompt panels are not enabled for conversion to a graphical user interface. 


1 The command prompt panels are enabled for conversion to a graphical user interface by including 
information about the panel content in the 5250 data stream. 


Help bookshelf. The name of the help bookshelf for this command. The possible values are: 
*NONE No help bookshelf is specified. 
*LIST The list of bookshelves in the user's book path. 


book-shelf The help bookshelf name. 


Help bookshelf information. Information describing the help bookshelf. 


See Help Bookshelf Information for more details about help bookshelf information. 


Help identifier. The name of the general help module for the names of the help identifiers for this 
command. The possible values are: 


*NONE No help identifier is specified. 
*CMD The name of the command is used. 


help-ID-name A user-specified help module was used. 


Help panel group library name. The name of the library in which the panel group resides. 


Help panel group name. The name of the panel group in which the online help information exists for this 
command. If *NONE is returned, no help panel group is defined for this command. 


Length of a REXX exit entry. The length of one REXX exit entry. This value is currently 24. There are 10 
bytes for the REXX exit program name, 10 bytes for the REXX exit library name, and 4 bytes for the 
REXX exit code. 

Length of help bookshelf information. The length of the help bookshelf. 


Maximum positional parameters. The maximum number of parameters than can be coded in a positional 
manner for this command. The possible values are: 


-1 No maximum positional coding limit was specified for this command. 


0 through 75 +The maximum number of parameters that can be coded in a positional manner for this 
command. 


Message file library name. The name of the library in which the message file resides. 


Message file name. The message file from which messages identified on the DEP statements used to define 
the command are retrieved. 


Mode information. The mode of operating environment to which the command applies. The characters of 
this field are as follows, and they can have a value of 0 (does not apply) or 1 (does apply): 


1 Production mode 


2 Debug mode 


3 Service mode 


4-10 Reserved 


Multithreaded job action. The action to take when a command that is not threadsafe is called in a 
multithreaded job. The possible values are: 


0 Use the action specified in QMLTTHDACN system value. 
1 Run the command. Do not send a message. 
2 Send an informational message and run the command. 


3 Send an escape message, and do not run the command. 


If the threadsafe indicator is either threadsafe or conditionally threadsafe, the multithreaded job action value 
will be returned as 1. 


Number of REXX exit entries. The number of times the REXX exit entries are repeated. These fields are 
REXX exit program name, REXX exit program library name, and REXX exit code. 


Offset to help bookshelf information. The offset to the help bookshelf information. 


Product library. The name of the product library that is in effect during the processing of the command. 
The possible values are: 


*NOCHG The product library does not change for the processing of this command. 
*NONE There is no product library in the job's library list. 


library-name The name of the library that is used as the product library during the processing of the 
command. 


Prompt message file library name. The name of the library in which the prompt message file resides. 


Prompt message file name. The name of the message file that contains the prompt text for this command. 
If *NONE is returned, no message file was specified for prompt text. 


Prompt override program call state. The state the prompt override program is called from. The possible 
values are: 


*S The prompt override program is called from the system state. 


*U The prompt override program is called from the user state. 


Prompt override program name. This is the name of the prompt override program that replaces default 
values (on the prompt display) with the current actual values for the parameter. If *NONE is returned, no 
prompt override program was specified for this command. 


Reserved. An ignored field. 


Restricted to target release. The version, release, and modification level to which this command is 
restricted. If this field is blank, the command can be used in the current release. This applies only to a 
command used in a CL program. It must match the contents of the target release parameter on the Create 
CL Program (CRTCLPGM) command. See the CRTCLPGM command for more information. This field 
has the format VvVRrMm, where: 


Vv __ The character V is followed by a 1-character version number. 
Rr ~The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


REXX command environment library name. The name of the library in which the REXX command 
environment program resides. 


REXX command environment name. The command environment program that is active when the REXX 
CPP starts to run. The REXX interpreter calls this program to process commands encountered in the REXX 
procedure. The possible values are: 


*COMMAND The OS/400 control language command environment is used. 


*CPICOMM ~~ The Common Programming Interface (CPI) for Communications command 
environment is used. CPICOMM is the command environment used for CL commands 
that are embedded within a REXX procedure. 


program-name The name of the program to process commands found in the REXX procedure. 


REXX exit code. A value which controls the conditions in which the REXX exit program is called. The 
possible values are: 


2 The exit program is called whenever an external function or subroutine has been called by the 
REXX program. The exit program is responsible for locating and calling the requested routine. 


3. The exit program is called whenever the interpreter is going to call a command. The exit program is 
responsible for locating and calling the command. 


4 The exit program is called whenever a REXX instruction or function attempts an operation on the 
REXX external data queue. 


5 The exit program is called when session input or output operations are attempted. 


7 The exit program is called after running each clause of the REXX procedure to determine whether it 
must be stopped. 


8 The exit program is called after running each clause of the REXX program to check if tracing must 
be turned on or off. 


9 The exit program is called before interpretation of the first instruction of a REXX procedure. 


10 The exit program is called after interpretation of the last instruction of a REXX procedure. 


REXX exit program library name. The name of the library in which the REXX exit program resides. 


REXX exit program name. The exit program used when the REXX interpreter is started under the 
conditions specified by the REXX exit code for this program. 


REXX source file library name. The name of the library in which the REXX source file resides. 


REXX source file member name. The name of the source file member that contains the REXX procedure 
that is the command processing program. 


REXX source file name. The name of the source file that contains the REXX procedure that is the 
command processing program. The possible values are: 


QREXSRC The IBM-supplied source file, QREXSRC, contains the source member that is used. 


source-file-name The name of the REXX source file that is used. 


Search index library name. The name of the library in which the help search index resides. 
Search index name. The name of the search index for this command. The possible values are: 
*NONE No help search index is specified. 


search index name The name of the help search index that is used. 


Source file library name. The name of the library in which the source file resides. 


Source file member name. The name of the source file member that contains the command definition 
statements used to create the command. 


Source file name. The name of the source file that contains the source file member used to create the 
command. 


Text description. The user text, if any, used to briefly describe the command and its function. 
Threadsafe indicator. Whether the command can be used safely in 
a multithreaded job. 
The possible values are: 
0 The command is not threadsafe and should not be used 


in a multithreaded job. The value for the multithreaded job action field defines the action to be taken 
by the command analyzer when the command is used in a multithreaded job. 


1 The command is threadsafe and can be used safely in a 
multithreaded job. 


2 The command is threadsafe under certain conditions. See the documentation for the command to 
determine the conditions under which the command can be used safely in a 


multithreaded job. 


Validity check program call state. The state the validity check program is called from. The possible 
values are: 


*S The validity check program is called from the system state. 


*U_ The validity check program is called from the user state. 


Validity check program library name. The name of the library in which the validity check program 
resides. 


Validity check program name. The name of a program that performs additional user-defined validity 
checking on the parameters in the command. If *NONE is returned, no separate user-defined validity 
checking is done for this command. All validity checking is done by the command analyzer and the 
command processing program. 


Where allowed to run. The environments in which this command is allowed to run. The characters of this 
field are as follows, and they can have a value of 0 (does not apply) or 1 (does apply): 


1 Batch program (*BPGM) 

2 Interactive program (*IPGM) 

Can be run using QCMDEXC, QCAEXEC, or QCAPCMD (*EXEC) 
Interactive job (*INTERACT) 

Batch job (*BATCH) 


Batch REXX procedure (*BREXX) 


Y Dn na Be WwW 


Interactive REXX procedure (*IREXX) 


8-15 Reserved 


Error Messages 


Message ID Error Message Text 

CPF2150E Object information function failed. 

CPF2151E Operation failed for &2 in &1 type *&3. 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3C21 E Format name &1 is not valid. 

CPF3C24 E Length of the receiver variable is not valid. 
CPF3C90 E Literal value cannot be changed. 

CPF6250 E Cannot display or retrieve command &1 in library &2. 
CPF8103 E Command &4 in &9 damaged. 

CPF8122 E &8 damage on library &4. 

CPF8123 E Damage on object information for library &4. 
CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 

CPF9803 E Cannot allocate object &2 in library &3. 

CPF9807 E One or more libraries in library list deleted. 
CPF9808 E Cannot allocate one or more libraries on library list. 


CPF9810 E Library &1 not found. 


CPF9820 E Not authorized to use library &1. 
CPF9830 E Cannot assign library &1. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V2R2 


Top | Program and CL Command APIs | APIs by category 


Retrieve Module Information (QBNRMODI) API 


Required Parameter Group: 


Receiver variable Char(*) 
Length of receiver variable Binary(4) 
Format name Char(8) 


Qualified module name Char(20) 
Error Code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The Retrieve Module Information (QBNRMODI) API lets you retrieve module information and place it 
into a single variable in the calling program. The amount of information returned is limited to the size of the 
variable. This information is similar to the information returned using the Display Module (DSPMOD) 
command. 
You can use the QBNRMODI API to retrieve the following: 

e Module creation information 

e Module compatibility information 

e Module SQL attributes 


e Module size information 


Authorities and Locks 


Library Authority 
*EXECUTE 

Module Authority 
*USE 

Module Lock 
*SHRRD 


Required Parameter Group 


Receiver variable 
OUTPUT; CHAR(*) 
The variable that is to receive the information requested. The minimum size for this area is 8 bytes. 


You can specify the size of this area to be smaller than the format requested if you specify the 
length of receiver variable parameter correctly. As a result, the API returns only the data that the 


area can hold. 
Length of receiver variable 
INPUT; BINARY(4) 


The length of the receiver variable. If this value is larger than the actual size of the receiver 
variable, the results may not be predictable. The minimum value is 8. 


Format name 
INPUT; CHAR(8) 


The content and format of the information returned for the module. 
The possible format names are: 
MODIOI100 Basic module information. 


MODIO200 Module size information. 


Qualified module name 
INPUT; CHAR(20) 


The first 10 characters contain the module name. The second 10 characters contain the name of the 
library where the module is located. 


You can use these special values for the library name: 
*CURLIB The job's current library 


*LIBL The library list 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


MODI0100 Format 


The following information is returned for the MODIO100 format. For detailed descriptions of the fields in 
the table, see Field Descriptions. 


[Offset 
= Hex |Type Field 


[ 94 | 5E |CHARGO) [Reserved = ~=~~SOSC~C~CS 
[ 104 | 68 |CHARG0)  |Moduleowner. —~—~—~SCSCS~S*S 
[114 | 72 |CHAR@) [Reserved ~~ ~SCS 
[116 | 74 |BINARY@) |ModuleCCSID.——~—~—~CS 
[ 201 | C9 |CHARG) [Reserved ~~~SOSOC~CS~S*~*~S 
[212 | D4 |CHARG)  |Debugdata —=~=~=~S~S~*~<“CS~S*~*~S~S 
[ 213 | D5 |CHARG) [Module compressed status —~—~=~S~S~S~S~*S 
[214 | Dé |CHAR@) [Reserved ~~~ SCS 
[ 204 | BO |CHARG)  |Modulestae +S 
A ee eT 
ae [ EC [CHARG) — ees mociie eae 
[242 | F2 |CHAR@) [Release module createdfor —~—~—~S~*S 
[277 | 115 |CHARG)  |Storagemodel  ~=~=~=~S~SOC~*~*~CS 
[278 | 116 |CHAR@ [Reserved ~~~SCS~S~S 


| 288 | 128 [CHAR@8) [Reserved 
| 356 | 164 |BINARY(4) [Number of SQL statements = 
| 360 [ 168 |CHAR(I8) — [Relationaldatabase = 
| 378 | 17A [CHARCO) ~~ |Commitmentcontrol = 
[388 | 184 |CHAR(0)  |Allowcopyofdata+=~=~CS*S*S 
[| 398 [ 18E |CHAR(IO) = |CloseSQLcursor 
| 418 [| 1A2 |CHARO) = [Dateformat; 
| 428 [ 1AC |CHAR(1) ~~ [Dateseparator = 
| 429 | 1AD [CHAR(O)  |Timeformat; == 
| 439 | 1B7 |[CHAR() ~~ [Timeseparator = 
[440 | 1B8 |CHARGO) [Delay PREPARE ——~—~SCS 
| 450 [| 1C2 [CHARMO)  [Allowblocking = 
| 460 | 1CC |CHAR(0) ~— [Defaultcollectionname = 
[ 470 | 1D6 |CHAR(0) |SQLpackagename = —(i‘“‘sSC~™S 
| 480 | 1EO [CHAR(I0) — [SQL package libraryname = 
[490 | IEA |CHAR(0) [Dynamic user profile ..+~~SOSCS* 
| 500 [ 1F4 |CHAR(I0) — [SQL sort sequence tablename = 
[ 310 | IFE |CHAR(0) [SQL sort sequence table library name —— 
[520 | 208 |CHAR(0) [SQL language identifier += ~~~~SOS™S 
[| 530 [ 212 |CHAR(IO) ~— |Connectionmethod = 
| 540 | 21C |BINARY(4) |SQLpathoffset 
| 544 | 220 |BINARY(4) |SQLpathlength == 
| 548 [ 224 |CHAR(*) ~~ [Reserved 
Module information through offsets 

; | — |CHARC*) [Program entry procedurename 
[ff CHARG) [SQL path 
; = [| ~~ [CHARC*) [Licensed Internal Code options 


MODI0200 Format 


The following information is returned for the MODI0200 format. For detailed descriptions of the fields in 
the table, see Field Descriptions. 


| Offset 
| Dec | Hex |Type Field 


[| 0 [ 0 JBINARY() [Bytesreturned = = = 
[| 4 [ 4  |BINARY(@)  [Bytesavailable 9 
[| 8 | 8 |CHARCO) ~~ [Modulename = = = 
[ 18 [ 12 |CHAR(O) ~~ [Modulelibraryname = 


Module size and limit information 


| 28 | 1C [BINARY(4) |Current total module size 


BINARY(4) [Maximum module size SSS 
INARY(4) [Current procedures and constants size 
[BINARY(4) {Maximum procedures and constants size 
[BINARY(4) [Current debug space size 
INARY(4)  [Maximumdebug space size = 
[BINARY(4) [Current associated space size 
[BINARY(4) [Maximum associated space size 
INARY(4) [Current module constants size 
[BINARY(4) [Maximum module constants size 
[BINARY(4) [Current static storage size 
[BINARY(4) [Maximum static storage size 
[BINARY(4) |Current dictionary mapping table size 
[BINARY(4) [Maximum dictionary mapping table size 
[BINARY(4) [Current exception mapping table size 
[BINARY(4) [Maximum exception mapping table size 
BINARY(4) [Current exception mapping table list area size 
[BINARY(4) [Maximum exception mapping table list area size 
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BINARY(@ |Current string directory component size 
BINARY(4) [Maximum dictionary componentsize 
BINARY(4) |Current initialization component size 
INARY(4) [Maximum type information component size 
INARY(4) |Current static storage work area size 
[est INARY(4) [Maximum binding work area size =~ 
[ 196 [C4 [BINARY(@) |Current number of procedures ———~SCSCSCS~™S 
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[212 | D4 [CHAR(4) [Reserved 
| 224 | EO |BINARY(8)  |Maximumstatic storage size-long 


324 144 |BINARY(4) Offset to largest automatic storage allocation 
procedure 

328 148 |BINARY(4) Length of largest automatic storage allocation 
procedure 

332 14C |BINARY(4) Current Licensed Internal Code stack allocation 
size 

336 150 |BINARY(4) Maximum Licensed Internal Code stack 
allocation size 

340 154. |BINARY(4) Offset to largest Licensed Internal Code stack 
allocation procedure 

344 158 |BINARY(4) Length of largest Licensed Internal Code stack 
allocation procedure 


| 348 | 15C [BINARY(4) [Current debug statement mapping table size 
[ 352 | 160 [BIN VARY (4) [Maximum debug statement mapping table size 


164. |BINARY(4) Offset to largest debug statement mapping table 
procedure 
BINARY(4) Length of largest debug statement mapping 
table procedure 


16C [BIN VARY (4) [Current exception statement mapping table size 


170 |BINARY(4) Maximum exception statement mapping table 
size 
372 174 |BINARY(4) Offset to largest exception statement mapping 
table procedure 
376 178 |BINARY(4) Length of largest exception statement mapping 
table procedure 


| 380 17C [BIN ARY(4) [Current machine instruction range mapping size 


384 180 |BINARY(4) Maximum machine instruction range mapping 
| | | i 
388 184 |BINARY(4) Offset to largest machine instruction range 
mapping procedure 
392 188 |BINARY(4) Length of largest machine instruction range 
mapping procedure 


[400 | 190 |BINARY@) [Maximum largest procedure size —~—~S~*S 
[ 404 | 194 |BINARY@) [Offset to largest procedure name ——~—~S~*S 


| 412 19C |CHAR(*) Reserved 
[Procedure information through offsets 


CHAR(*) Largest automatic storage allocation procedure 
name 

CHAR(*) Largest Licensed Internal Code stack allocation 
procedure name 

CHAR(*) Largest debug statement mapping table 
procedure name 

CHAR(*) Largest exception statement mapping table 
procedure name 

CHAR(*) Largest machine instruction range mapping 
procedure name 


| CHAR(*) Largest procedure name 


Field Descriptions 


For more detailed information than that provided in the following field descriptions, refer to the Control 
Language (CL) information in the iSeries Information Center for the Create XXX Module (CRTxxxMOD) 
commands. 


Allow blocking. Indicates whether blocking is used to improve the performance of certain SQL statements. 
Possible values are: 


*NONE Blocking is not used. 


*READ Blocking is used for read-only cursors when running COMMIT(*NONE) and there are no 
EXECUTE or EXECUTE IMMEDIATE statements. 


*ALLREAD Blocking is used for all read-only cursors when running COMMIT(*NONE) or 
COMMIT(*CHG). 


Allow copy of data. Indicates whether a copy of the data can be used in the implementation of an SQL 
query. 
Possible values are: 

*NO A copy of the data cannot be used. 

*YES A copy of the data can be used when needed. 


*OPTIMIZE The system determines whether a copy of the data is used for optimal performance. 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 


Close SQL cursor. Specifies when SQL cursors are implicitly closed and SQL prepared statements are 
implicitly discarded. 


Possible values are: 
*ENDMOD When the module ends. 


*ENDACTGRP When the activation group is deleted. 


Commitment control. The level of commitment control that was specified on the SQL precompile. 
Possible values are: 


*NONE No commitment control was specified on the SQL precompile. Uncommitted changes in other 
jobs can be seen. 


*CHG Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements, and updated, deleted, or inserted rows (records) are locked until the end 
of the unit of work (transaction). Uncommitted changes in other jobs can be seen. 


*CS Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements, and updated, deleted, or inserted rows (records) are locked until the end 
of the unit of work (transaction). A row (record) that is selected but not updated is locked until 
the next row (record) is selected. Uncommitted changes in other jobs cannot be seen. 


*ALL Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements, and all rows selected, updated, deleted, or inserted are locked until the 
end of the unit of work (transaction). Uncommitted changes in other jobs cannot be seen. 


Connection method. Indicates whether connections are allowed to one or more relational databases. 
The following special values can be returned: 


*RUW Only one connection to a relational database is allowed. Consecutive CONNECT statements 
result in the previous connection being disconnected before a new connection is established. 


*DUW Connections to several relational databases are allowed. Consecutive CONNECT statements to 
additional relational databases do not result in disconnection of previous connections. The SET 
CONNECTION statement can be used to switch between connections. Read-only connections 
may result. 


Conversion required. Indicator as to whether the module has been converted to reduced instruction set 
computer (RISC) format or if conversion is still required. 


0 Conversion is not required. It has already been converted. 


ZI Conversion is required. 


Creation data. 2*Whether the module has all creation data and if that data is observable or unobservable. 
All observable creation data is needed to re-create the module using the Change Module (CHGMOD) 
command. All creation data (either observable or unobservable) is needed to convert the module during 
restore. *& 


0 *NO. Not all the creation data is present. 
I *YES. All the creation data is present and observable. 


“+2 *UNOBS. All the creation data is present but not all of that data is observable. 


Current alias component size. The size, in bytes, of the alias component. The size is the decompressed 
size, even if the module is compressed. The current size increases as more data objects, particularly arrays 
and structures, are added to the module. 


Current associated space size. The size, in bytes, of the associated space. The number of SQL statements 
in the module may affect the current size. 


Current automatic storage allocation size. The size, in bytes, of the largest automatic storage allocation 
associated with the procedure referenced by the offset to the largest automatic storage allocation procedure 
name for this module. The current size increases as more automatic variables and bound procedure calls are 
added. 


Current binding specifications component size. The size, in bytes, of the binding specifications 
component. The size is the decompressed size, even if the module is compressed. The current size increases 
as imported and exported procedures and data items are added. 


Current binding work area size. The size, in bytes, of the binding work area. The size is the 
decompressed size, even if the module is compressed. The current size increases as imports and exports are 
added to the module. 


Current debug space size. The size, in bytes, of the debug space. The size is the decompressed size, even 
if the module is compressed. See the debug view (DBGVIEW) parameter of the Create xxx Module 
(CRTxxxMOD) command for more information on the different debug view levels you can specify at 
create time. You can completely remove the debug view data from the module by using the remove 
observability (RMVOBS) parameter of the Change Module (CHGMOD) command. 


Current debug statement mapping table size. The size, in bytes, of the debug statement mapping table 
associated with the procedure referenced by the offset to the largest debug statement mapping table 
procedure name for this module. The current size increases as statements are added or increase in 
complexity. 


Current dictionary component size. The size, in bytes, of the dictionary component. The size is the 
decompressed size, even if the module is compressed. The current size increases as more data objects, 
exception handlers, constants, and procedures are added. 


Current dictionary mapping table size. The amount of space, in bytes, for the dictionary mapping table. 
The size is the decompressed size, even if the module is compressed. The dictionary mapping table does not 
exist if the DBGVIEW(*NONE) option is used when the module is created. If it does exist, its current size 
depends on the number of different variables that are declared in the module. 


Current exception mapping table list area size. The amount of space, in bytes, for the exception mapping 
table list area. The size is the decompressed size, even if the module is compressed. The current size 
depends on the number of exception handlers that are enabled in the code. The handlers could be either 
defined by the user or defined by the compiler to handle exceptions in the generated code. 


Current exception mapping table size. The amount of space, in bytes, for the exception mapping table. 
The size is the decompressed size, even if the module is compressed. The current size depends on the 
number of exception handlers that are either declared by the user or defined by the compiler to handle 
exceptions in the generated code. 


Current exception statement mapping table size. The size, in bytes, of the exception statement mapping 
table associated with the procedure referenced by the offset to the largest exception statement mapping 
table procedure name for this module. This table is used to map high-level language statements to Licensed 
Internal Code instructions. The current size increases as statements are added or increase in complexity. 


Current initialization component size. The size, in bytes, of the initialization component. The size is the 
decompressed size, even if the module is compressed. The current size increases as more statements to 
statically initialize data objects are added. 


Current instructions component size. The size, in bytes, of the instructions component. The size is the 
decompressed size, even if the module is compressed. 


Current largest procedure size. The size, in bytes, of the largest procedure in the module. 


Current Licensed Internal Code stack allocation size. The size, in bytes, of the Licensed Internal Code 
stack allocation associated with the procedure referenced by the offset to the largest Licensed Internal Code 
stack allocation procedure name for this module. The current size increases at higher levels of optimization. 


Current literal pool component size. The size, in bytes, of the literal pool component. The size is the 
decompressed size, even if the module is compressed. The current size increases as more literals or 
initializations are added to the module. 


Current machine instruction range mapping size. The size, in bytes, of the machine instruction range 
mapping associated with the procedure referenced by the offset to the largest machine instruction range 
mapping procedure name for this module. The number of times exception handlers are enabled and disabled 
affects the current size. Also, some instructions, like packed decimal arithmetic, affect this size. 


Current module constants size. The amount of space, in bytes, for module constants. The size is the 
decompressed size, even if the module is compressed. Changing the number of large aggregate constants or 
the number of smaller constants may affect the current size. 


Current number auxiliary storage segments. The number of auxiliary storage segments used by this 
module. 


Current number of copyrights. The number of copyrights defined in this module. 
Current number of procedures. The number of procedures declared in this module. 


Current number of static storage allocations. The number of static storage allocations used by this 
module. The current number increases as static data items (particularly imported data items) are added to 
the module. 


Current procedures and constants size. The current amount of space, in kilobytes, for procedures and 
constants. The size is the decompressed size, even if the module is compressed. The current size increases 
as more instructions are added. The number of literals and the size of the literal values may have an effect 
on the current size. This number could be zero in which case it means the size is less than 1 kilobyte. 


Current static storage size. The amount of static storage, in bytes, required for the module. The size is the 
decompressed size, even if the module is compressed. As more and larger static and exported variables are 
declared, the current size increases. #*A value of 4294967295 will be given if 4 gigabytes (4294967296) or 
greater is needed. In this case, the current static storage size - long field should be used instead. 


Current static storage size - long. The current amount of static storage, in bytes, required for the module. 


“4 


Current static storage work area size. The size, in bytes, of the static storage work area. The size is the 
decompressed size, even if the module is compressed. The current size increases as static data items or 
initializations are added to the module. 


Current string directory component size. The size, in bytes, of the string directory component. The size 
is the decompressed size, even if the module is compressed. The current size increases as imported and 


exported procedures and data items are added. 


Current total module size. The size of the module, in kilobytes. The size is the decompressed size, even if 
the module is compressed. 


Current type information component size. The size, in bytes, of the type information component. The 


size is the decompressed size, even if the module is compressed. The current size increases as more 
procedures are added to the module. 


Date format. Specifies the format used when accessing date result columns through SQL. All output date 
fields are returned in this format. For input date strings, the value you specify is used to determine whether 
the date is a valid format. 


Possible values are: 
*USA — USA format 
*ISO International Standards Organization format 
*EUR — European format 
*JIS Japanese Industrial Standard Christian Era 
*MDY Month/day/year format 
*DMY  Day/month/year format 
*YMD_ = Year/month/day format 


*JUL Julian format 


Date separator. Specifies the separator used when accessing date result columns. A blank value indicates 
either that there are no SQL statements or that the separator character is a blank. Assume the latter if the 
number of SQL statements parameter is not zero. 


Debug data. Indicates whether debug data exists for this module. If debug data exists, the module may be 
debugged using the source debugger. 


O The module does not contain debug data. 


I The module does contain debug data. 


Default collection name. Specifies the collection name used for the unqualified names of tables, views, 
indexes, and SQL packages. *NONE indicates there is no default collection. 


Delay PREPARE. Indicates whether SQL prepare processing can be delayed until the statement is actually 
used. 


Possible values are: 
*YES Prepare processing can be delayed. 


*NO _ Prepare processing cannot be delayed. 


Dynamic user profile. Specifies the user profile used for dynamic SQL statements. 
The following special values can be returned: 


*USER Local dynamic SQL statements are run under the profile of the module's user. Distributed 
dynamic SQL statements are run under the profile of the SQL package's user. 


*OWNER Local dynamic SQL statements are run under the profile of the module's owner. Distributed 
dynamic SQL statements are run under the profile of the SQL package's owner. 


Earliest release module can be restored to. The earliest version, release, and modification level of the 
operating system to which the module may be restored. 


The field has a VvVRrMm format, where: 
Vv _ The character V is followed by a 1-character version number. 
Rr — The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


Enable performance collection. The level of performance collection enabled for this module. 
The following values can be returned: 


'00'X *NONE or '10'X *PEP This gives the entry/exit information for the PEP only. No entry/exit 
hooks in the module's internal procedures and no precall or postcall 
hooks around calls to other procedures are included. Note: If *NONE 
is shown and the module was created or re-created on an iSeries 
server running Version 3 Release 6 Modification 0 prior to the 
installation of PTF MF11968, the module will not have any 
performance collection enabled. To enable performance collection, 
use one of the following commands and specify 
ENBFPRCOL(*PEP): 


e Change Module (CHGMOD) 
e Change Program (CHGPGM) 
e Change Service Program (CHGSRVPGM) 


'50'X *ENTRYEXIT *NONLEAF This gives the entry/exit information on all of the non-leaf procedures 
in the module. This includes the PEP routine. This is useful to capture 
information on most routines but not at the expense of destroying the 
‘leaf-ness' of the leaf procedures. 


'70'X *ENTRYEXIT *ALLPRC This gives the entry/exit information on all the procedures of the 
module (including those that were leaf procedures). This includes the 
PEP routine. This is useful to capture information on all procedures. 


'DO'X *FULL *NONLEAF This gives the entry/exit information on all the procedures of the 
module that are not leaf procedures. This includes the PEP routine. 
Precall and postcall hooks around calls to external procedures are 
included. 


'FO'X *FULL *ALLPRC This gives the entry/exit information on all procedures of the module 
(including those that were leaf procedures). This includes the PEP 
routine. Precall and postcall hooks around calls to external procedures 
are also included. This is useful to capture information on all 
procedures. 


Intermediate language (IL) data. Whether the module has intermediate language (IL) data. 
I The module contains IL data. 


O The module does not contain IL data. 


Language identifier. The language identifier used when the module was compiled. A 


possible special value is: 


*JOBRUN The language identifier associated with the job at the time the program (in which the 
module is bound) runs. 


Note: This language identifier does not apply to DB2 for iSeries statements that may be 
contained in this module. 


Largest automatic storage allocation procedure name. The name of the largest automatic storage 
allocation procedure in the module. 


Largest debug statement mapping table procedure name. The name of the largest debug statement 
mapping table procedure in the module. 


Largest exception statement mapping table procedure name. The name of the largest exception 
statement mapping table procedure in the module. 


Largest Licensed Internal Code stack allocation procedure name. The name of the largest Licensed 
Internal Code stack allocation procedure in the module. 


Largest machine instruction range mapping procedure name. The name of the largest machine 
instruction range mapping procedure in the module. 


Largest procedure name. The name of the largest procedure in the module. 


Length of largest automatic storage allocation procedure name. The size, in bytes, of the name of the 
largest automatic storage allocation procedure in this module. 


Length of largest debug statement mapping table procedure name. The size, in bytes, of the name of 
the largest debug statement mapping table procedure. 


Length of largest exception statement mapping table procedure name. The size, in bytes, of the name 
of the largest exception statement mapping table procedure. 


Length of largest Licensed Internal Code stack allocation procedure name. The size, in bytes, of the 
name of the largest Licensed Internal Code stack allocation procedure. 


Length of largest machine instruction range mapping procedure name. The size, in bytes, of the name 
of the largest machine instruction range mapping procedure. 


Length of largest procedure name. The size, in bytes, of the name of the largest procedure. 


Length of Licensed Internal Code options. The size, in two-byte characters, of the Licensed Internal 
Code options string. This is 0 if no Licensed Internal Code options were used for this module. 


Length of program entry procedure name. The size, in bytes, of the program entry procedure name. 


Licensed Internal Code options. The Licensed Internal Code options being used by the module. This field 
is specified in UCS-2 (CCSID 13488). 


Maximum alias component size. The maximum possible size, in bytes, of the alias component. 
Maximum associated space size. The maximum possible size, in bytes, of the associated space. 


Maximum automatic storage allocation size. The maximum possible size, in bytes, of the largest 
automatic storage allocation associated with a procedure for a module. 


Maximum binding specifications component size. The maximum possible size, in bytes, of the binding 


specifications component. 
Maximum binding work area size. The maximum possible size, in bytes, of the binding work area. 
Maximum debug space size. The maximum possible size, in bytes, of the debug space. 


Maximum debug statement mapping table size. The maximum possible size, in bytes, of the debug 
statement mapping table associated with a procedure for a module. 


Maximum dictionary component size. The maximum possible size, in bytes, of the dictionary component. 


Maximum dictionary mapping table size. The maximum possible amount of space, in bytes, for the 
dictionary mapping table. 


Maximum exception mapping table list area size. The maximum possible amount of space, in bytes, for 
the exception mapping table list area. 


Maximum exception mapping table size. The maximum possible amount of space, in bytes, for the 
exception mapping table. 


Maximum exception statement mapping table size. The maximum possible size, in bytes, of the 
exception statement mapping table associated with a procedure for a module. 


Maximum initialization component size. The maximum possible size, in bytes, of the initialization 
component. 


Maximum instructions component size. The maximum possible size, in bytes, of the instructions 
component. 


Maximum largest procedure size. The maximum possible size, in bytes, of a procedure in a module. 


Maximum Licensed Internal Code stack allocation size. The maximum possible size, in bytes, of the 
Licensed Internal Code stack allocation associated with a procedure for a module. 


Maximum literal pool component size. The maximum possible size, in bytes, of the literal pool 
component. 


Maximum machine instruction range mapping size. The maximum possible size, in bytes, of the 
machine instruction range mapping associated with a procedure for a module. 


Maximum module constants size. The maximum possible amount of space, in bytes, for module 
constants. 


Maximum module size. The largest size, in kilobytes, allowed for a module. 


Maximum number auxiliary storage segments. The maximum possible number of auxiliary storage 
segments used by a module. 


Maximum number of copyrights. The maximum possible number of copyrights defined in a module. 


Maximum number of parameters. The maximum number of parameters that are to be received by the 
program entry procedure if one is present in the module. 


Maximum number of procedures. The maximum possible number of procedures declared in a module. 


Maximum number of static storage allocations. The maximum possible number of static storage 
allocations used by a module. 


Maximum optimization level. The highest level of optimization you may request. If observability has been 
removed from the module, this maximum optimization level value might not be the same as the one 
specified when the module was created. 


Maximum procedures and constants size. The maximum possible amount of space, in kilobytes, for 
procedures and constants. This number could be zero, in which case it means the size is less than 1 kilobyte. 


Maximum static storage size. The maximum possible amount of static storage, in 2*kilobytes, “Krequired 
for a module. 


Maximum static storage size - long. The maximum possible amount of static storage, in bytes, required 
for a module. * 


Maximum static storage work area size. The maximum possible size, in bytes, of the static storage work 
area. 


Maximum string directory component size. The maximum possible size, in bytes, of the string directory 
component. 


Maximum type information component size. The maximum possible size, in bytes, of the type 
information component. 


Minimum number of parameters. The minimum number of parameters that are to be received by the 
program entry procedure if one is present in the module. 


Module attribute. The programming language in which the module is written or the product that produced 
the module. 


Module CCSID (Coded Character Set ID). The coded character set identifier (CCSID) for this module. 


Module compressed status. Indicates whether the module is in compressed format. 
The following values can be returned: 


65535 The module is not restricted to a maximum optimization level. It can be retranslated to any of 
the supported optimization levels. 65535 is also known as *NOMAX. 


40 Maximum level of optimization. This level includes all the optimizations performed at 
optimization level 30. In addition, it includes optimization that disables call and instruction 
tracing. Thus, tracing of modules created at this optimization level cannot be done. 


30 More optimization is performed in addition to those performed at optimization level 20. 
Variables cannot be changed but can be displayed while the program is being debugged. 
However, the displayed value of the variable during debugging may not be its actual value. 30 is 
also known as *FULL. 


20 Some optimization is performed on the generated code. When the module optimized at this level 
is being debugged, the variables can be displayed but not changed. This level improves the 
performance of the module slightly over level 10. 20 is also known as *BASIC. 


10 No additional optimization is performed on the generated code. Variables can be displayed and 
changed when the program is being debugged. With no optimization of the code, this value 
provides the lowest level of module performance. 10 is also known as *NONE. 


0 The module is not in a compressed status. 


I The module is in a compressed status. 


Module creation date and time. The date and time when the module was created. The creation date and 
time field is in the CY YMMDDHHMMSS format as follows: 


C Century, where 0 indicates years 19xx and 1 indicates years 20xx. 
YY Year 

MM _ Month 

DD Day 

HH Hour 

MM _ Minute 

SS Second 


Module domain. The domain of the module. 
The possible value is: 


S The module is system domain. 


Module library name. The library that contains the module. 
Module name. The name of the module whose information is being given. 


Module owner. The name of the user profile of the user who owns this module. 


Module state. The state of the module. 
The Possible values are: 


I The module is inherit state and can be bound together with either system state modules or user state 
modules. 


S The module is system state and must be bound with other system state modules or inherit state 
modules. 


U_ The module is user state and must be bound with other user state modules or inherit state modules. 


Naming convention. The naming convention used for naming objects in SQL statements. 
Possible values are: 
*SQL The SQL naming convention is used. 


*SYS The system naming convention is used. 


Number of exported defined symbols. The number of exported procedures and variables in this module. 


Number of imported (unresolved) symbols. The number of imported procedures and variables in this 
module. 


Number of SQL statements. The number of DB2 UDB for iSeries statements contained in the module. 


Offset to largest automatic storage allocation procedure name. The offset from the beginning of the 


receiver variable where the largest automatic storage allocation procedure begins. 


Offset to largest debug statement mapping table procedure name. The offset from the beginning of the 
receiver variable where the largest debug statement mapping table procedure name begins. 


Offset to largest exception statement mapping table procedure name. The offset from the beginning of 
the receiver variable where the largest exception statement mapping table procedure name begins. 


Offset to largest Licensed Internal Code stack allocation procedure name. The offset from the 
beginning of the receiver variable where the largest Licensed Internal Code stack allocation procedure 
name begins. 


Offset to largest machine instruction range mapping procedure name. The offset from the beginning of 
the receiver variable where the largest machine instruction range mapping procedure name begins. 


Offset to largest procedure name. The offset from the beginning of the receiver variable where the largest 
procedure name begins. 


Offset to Licensed Internal Code options. The offset from the beginning of the receiver variable where 
the Licensed Internal Code options begin. 


Offset to program entry procedure name. The offset from the beginning of the receiver variable where 
the program entry procedure name begins. 


Optimization level. Optimization levels cause the translator to produce machine code that reduces the 
amount of system resources necessary to run the program. The more optimization, the more efficiently the 
module runs on the system. Also, with more optimization you may not be able to change or view variables 
that have been optimized. 


The Possible values are: 


65535 The module is not restricted to a maximum optimization level. It can be retranslated to any of 
the supported optimization levels. 65535 is also known as *NOMAX. 


40 Maximum level of optimization. This level includes all the optimizations performed at 
optimization level 30. In addition, it includes optimization that disables call and instruction 
tracing. Thus, tracing of modules created at this optimization level cannot be done. 


30 More optimization is performed in addition to those performed at optimization level 20. 
Variables cannot be changed but can be displayed while the program is being debugged. 
However, the displayed value of the variable during debugging may not be its actual value. 30 is 
also known as *FULL. 


20 Some optimization is performed on the generated code. When the module optimized at this level 
is being debugged, the variables can be displayed but not changed. This level improves the 
performance of the module slightly over level 10. 20 is also known as *BASIC. 


10 No additional optimization is performed on the generated code. Variables can be displayed and 
changed when the program is being debugged. With no optimization of the code, this value 
provides the lowest level of module performance. 10 is also known as *NONE. 


Profile data. The profile data attribute for the module. 


*NOCOL The collection of profile data is not enabled. The module will not collect profile data when it 
is included in a program or service program object. 


*COL The collection of profile data is enabled. The module will collect profile data when it is 
included in a program or service program object. 


Program entry procedure name. The name of the program entry procedure if one is present in the 
module. 


Program entry procedure name indicator. Indicates if a program entry procedure is present in the 
module. 


O The module does not have a program entry procedure. 


I The module does have a program entry procedure. 


Relational database. The default relational database that was specified on the SQL precompile. 
Possible values are: 
*LOCAL The module can access data only on the local system. 


Non-blank value other than *LOCAL The name associated with this module in the relational database 
index. 


Release module created for. The version, release, and modification level of the operating system for 
which the module was created. 


The field has a VvVRrMm format, where: 
Vv _ The character V is followed by a 1-character version number. 
Rr The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


Release module created on. The version, release, and modification level of the operating system that was 
running on the system when the module was created. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


Reserved. An ignored field. 
Sort sequence table library name. The name of the library that is used to locate the sort sequence table. 
Possible special values are: 

*LIBL The library list is searched when the program (in which the module is bound) runs. 


*CURLIB The current library is searched when the program (in which the module is bound) runs. 


Sort sequence table name. The name of the sort sequence table used when the module was compiled. 
Possible special values are: 


*HEX No sort sequence is used. 


*JOBRUN The SRTSEQ value associated with the job at the time the program (in which the 
module is bound) runs. 


*LANGIDSHR _ The shared sort sequence for the language identifier (LANGID). 
*LANGIDUNQ _ The unique sort sequence for the language identifier. 


Note: This sort sequence table does not apply to DB2 UDB for iSeries statements that 
may be contained in this module. 


Source file change date and time. The date and time when the source member that was used to create this 
module was last changed. The source file change date and time field is in the CY YMMDDHHMMSS 
format as follows: 


C Century, where 0 indicates years 19xx and 1 indicates years 20xx. 
YY Year 

MM _ Month 

DD Day 

HH Hour 

MM _ Minute 

SS Second 


Source file library name. The library that contained the source file that was used to create this module. 


Source file name. The source file that contained the source member that was used to create this module. If 
this field is blank, the module was created from an inline source file 


Source member name. The source file member from which this module was created. 


SQL language identifier. Returns the language identifier used when the module was compiled. This 
information is blank if the module does not contain any language identification information. 


The special value that can be returned is: 


*JOBRUN _ The language identifier is the LANGID associated with the job at the time the program (in 
which the module is bound) runs. 


SQL package library name. Specifies the name of the library containing the SQL package. A blank 
indicates the module is not to be distributed. 


The following possible special values can be returned: 


*LIBL The SQL package is found by looking for it in the library list when the program (in which 
the module is bound) runs. 


*CURLIB The SQL package is found in the current library when the program (in which the module is 
bound) runs. 


SQL package name. Specifies the name of the SQL package created on the relational database specified 
on the RDB parameter of the command that created this module. *NONE indicates that this is not a 
distributed module. 


SQL path. The list of libraries used during resolution of functions and data types within SQL statements. 
The list is in the form of repeating library names, each surrounded by double quotes and separated by 
commas. 


SQL path length. The length, in bytes, of the SQL path. 


SQL path offset. The offset, in bytes, from the beginning of this format definition to the beginning of the 
SQL path. 


SQL sort sequence table library name. Returns the name of the library that is used to locate the SQL sort 
sequence table. This information is blank either if the module does not contain any SQL sort sequence 
information, or if a special value was returned for the SQL sort sequence table name. 


The following possible special values that can be returned for the library are: 


*LIBL The SQL sort sequence table is found by looking for it in the library list when the program 
(in which the module is bound) runs. 


*CURLIB The SQL sort sequence table is found in the current library when the program (in which the 
module is bound) runs. 


SQL sort sequence table name. Returns the SQL statement sort sequence table name used when the 
module was created. This information is blank if the module does not contain any SQL sort sequence 
information. 


The following possible special values can also be returned: 
*HEX No SQL sort sequence is used for the SQL statements. 


*JOBRUN The SQL sort sequence is the SRTSEQ value associated with the job at the time the 
SQL statements within the module are run. 


*LANGIDSHR _ The shared SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


*LANGIDUNQ The unique SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


Note: This sort sequence table does not apply to DB2 UDB for iSeries statements that 
may be contained in this module. 


Storage model. Where the automatic and static storage for this bound module is allocated at run time. 
The following values can be returned: 

0 *SNGLVL Automatic and static storage are allocated from single-level storage. 

1 *TERASPACE Automatic and static storage are allocated from teraspace. 


2 *INHERIT Automatic and static storage are allocated from either single-level storage or 
teraspace, depending on the activation. 


Teraspace storage enabled. The teraspace storage capability for this module. 
Possible values are: 


‘00'X *NO The module is not teraspace storage enabled. 


‘80'X *YES The module is teraspace storage enabled. 


Text description. The text description that was provided for this module. 


Time format. Specifies the format used when accessing time -result columns through SQL. All output time 
fields are returned in this format. For input time strings, the value you specify is used to determine whether 
the time is a valid format. 


Possible values are: 


*USA USA format 


*[SO International Standards Organization format 


*EUR 


European format 


*JIS Japanese Industrial Standard Christian Era 


*HMS Hours/minutes/seconds format 


Time separator. Specifies the separator used when accessing time result columns. A blank value indicates 
that there are no SQL statements or that the separator character is a blank. Assume the latter if the number 
of SQL statements parameter is not zero. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3C19 E 
CPF3C21 E 
CPF3C24 E 
CPF3C90 E 
CPFSCE7 E 
CPF8122 E 
CPF8123 E 
CPF813D E 
CPF9801 E 
CPF9802 E 
CPF9803 E 
CPF9804 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error occurred with receiver variable specified. 
Format name &1 is not valid. 

Length of the receiver variable is not valid. 
Literal value cannot be changed. 

Error occurred while retrieving *MODULE data. 
&8 damage on library &4. 

Damage on object information for library &4. 
Service program &4 in &9 damaged. 

Object &2 in library &3 not found. 

Not authorized to object &2 in &3. 

Cannot allocate object &2 in library &3. 


Object &2 in library &3 damaged. 


CPF9806 E Cannot perform function for object &2 in library &3. 
CPF9807 E One or more libraries in library list deleted. 
CPF9808 E Cannot allocate one or more libraries on library list. 
CPF9810 E Library &1 not found. 

CPF9811 E Program &1 in library &2 not found. 

CPF9820 E Not authorized to use library &1. 

CPF9821 E Not authorized to program &1 in library &2. 
CPF9830 E Cannot assign library &1. 


API introduced: V3R6 


Top | Program and CL Command APIs | APIs by category 


Retrieve Program Associated Space 
(QCLRPGAS) API 


Required Parameter Group: 


Output data buffer Char(*) 
Length of output data buffer Binary(4) 
Qualified program name Char(20) 
Call stack counter Binary(4) 
Data handle Char(16) 
Length of data available Binary(4) 
Error code Char(*) 


Default Public Authority: “EXCLUDE 


Threadsafe: No 


The Retrieve Program Associated Space (QCLRPGAS) API allows you to retrieve information from the 
associated space of an original program model (OPM), user-state program in the user domain. This API is 
intended to be used only on programs created by the Create Program (QPRCRTPG) API. 


This API is used to retrieve information that was previously stored in the associated space. For example, it 
can be used by compilers at run time to retrieve information about the compilation process that was 
previously stored. The associated space of a program object is not a replacement for data areas or user 
spaces. It is recommended for static data only. 


Authorities and Locks 


Program Library Authority 
*USE 

Program Authority 
*ALL 

Program Lock 
*EXCLRD 


Required Parameter Group 
Output data buffer 
OUTPUT; CHAR(*) 


The information retrieved from the associated space. This information contains scalar data only. If 
information that was previously stored contained pointer data, the pointer data was not preserved. 


Length of output data buffer 
INPUT; BINARY(4) 
The length of the output data buffer, in bytes. If this value is larger than the actual size of the output 
data buffer, the results may not be predictable. 

Qualified program name 
INPUT; CHAR(20) 
The program object for which you want to retrieve data from the associated space. This must be an 
OPM, user-state program in the user domain. An error is returned if the program is an Integrated 
Language Environment (ILE) program, or if it is a system-state or system-domain program. The 


first 10 characters contain the program name, and the second 10 characters contain the library 
name. 


You can use the following special value for the program name: 


* Use a program in the call stack. The call stack counter contains the number of programs up 
the stack from the calling program to look for the program from which to retrieve data. 


You can use these special values for the library name: 
*CURLIB The job's current library 


*LIBL The library list 


Call stack counter 
INPUT; BINARY(4) 
A number greater than zero identifying the location in the call stack for the program if * is specified 


for the program name. This number is relative to the program that called this API. This parameter is 
ignored if the program name is not *. 


Data handle 
INPUT; CHAR(16) 
The identifier to retrieve the information from in the associated space. Specify the data handle that 
was previously used on the Store Program Associated Space (QCLSPGAS) API to store 


information in the associated space. If no data was previously stored at this data handle, no error is 
returned. The length of data available parameter will be set to 0 indicating no data was available. 


Length of data available 
OUTPUT; BINARY(4) 


Either the length of the data actually returned or the length of data available. 
The possible values follow: 


0 No data was previously stored at the data handle 
specified. 


From | to the value of the length of output The length of information available and 
data buffer parameter successfully returned in the output data buffer. 


Greater than the value of the length of 
output data buffer parameter 


The total length of data available. If the output data 
buffer is too small to hold all of the information 
available, the information is truncated to fit the 
available space. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 

CPF0301 E Length of data buffer is not valid. 

CPF0302 E Value for call stack counter not valid. 

CPF0304 E Operation not allowed for program &1 in library &2. 
CPF24B4 E Severe error while addressing parameter list. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF8100 E All CPF81xx messages could be returned. xx is from 01 to FF. 
CPF9803 E Cannot allocate object &2 in library &3. 

CPF9807 E One or more libraries in library list deleted. 

CPF9808 E Cannot allocate one or more libraries on library list. 

CPF9810 E Library &1 not found. 

CPF9811 E Program &1 in library &2 not found. 

CPF9820 E Not authorized to use library &1. 

CPF9821 E Not authorized to program &1 in library &2. 

CPF9830 E Cannot assign library &1. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V2R3 


Top | Program and CL Command APIs | APIs by category 


Retrieve Program Information (QCLRPGMI) API 


Required Parameter Group: 


Receiver variable Char(*) 
Length of receiver variable Binary(4) 
Format name Char(8) 


Qualified program name Char(20) 
Error Code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The Retrieve Program Information (QCLRPGMI) API lets you retrieve program information and place it 
into a single variable in the calling program. The amount of information returned is limited to the size of the 
variable. This information is the same as the information returned using the Display Program (DSPPGM) 
command. 
You can use the QCLRPGMI API to retrieve the following: 

e Program creation information 

e Program statistics 

e Program performance information 

e SQL statement information 

e 


ILE program size information 


Authorities and Locks 


Library Authority 
*EXECUTE 

Program Authority 
*READ 

Program Lock 
*SHRRD 


Required Parameter Group 


Receiver variable 
OUTPUT; CHAR(*) 


The variable that is to receive the information requested. The minimum size for this area is 8 bytes. 
You can specify the size of this area to be smaller than the format requested as long as you specify 


the length parameter correctly. As a result, the API returns only the data that the area can hold. 
Length of receiver variable 


INPUT; BINARY(4) 


The length of the receiver variable. If this value is larger than the actual size of the receiver 
variable, the results may not be predictable. The minimum value is 8. 


Format name 
INPUT; CHAR(8) 


The content and format of the information returned for the program. 
The possible format names are: 
PGMIOJ00 Basic program information for OPM and ILE programs. 


PGMI0200 Basic program information for OPM and ILE programs plus SQL statement 
information for OPM programs. 


PGMI0300 ILE program size information. 


Qualified program name 
INPUT; CHAR(20) 


The first 10 characters contain the program name. The second 10 characters contain the name of the 
library where the program is located. 


You can use these special values for the library name: 
*CURLIB The job's current library 


*LIBL The library list 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


PGMI0100 Format 


The following information is returned for the PGMIO100 format. Some of the fields returned are blank or 


zero if they do not apply to the type of program specified. For detailed descriptions of the fields in the table, 
see Field Descriptions. 


| Offset 
| Dec Hex /|Type Field 


| 0 0 BINARY(4) Bytes returned 
| 4 4 BINARY(4) Bytes available 


[Programcreation information = 
| 28 [ IC |CHAR(O) ~~ |Progamowner = = = = 
[ 48 [| 30 |CHAR(I3) — {Creation date and time 

| 71 | 47 |CHARCO) [Source filelibraryname == 
| 81 [| 51 |CHAR(O) — Source filemembername == 
| 91 [| 5B  |CHAR(3) [Source file updated date and time = 
| 104 | 68 |CHAR() — |Observableinformation == 
| 105 [ 69 |CHAR(1) — [Userprofileoption = 
[ 107 [ 6B |CHARG)  |Logcommands = ~SO~CS~*~CS 
| 108 [ 6C |CHAR() ~~ |AllowRTVCLSRC 
| 109 [ 6D |CHAR() ~~ |Fixdecimaldata = = 
| 110 | 6E |CHAR(0)  |Textdescription = 
| 160 [ AO |CHAR() ~~ |[Typeofprogam == 
| 161 [ Al |CHAR() _ [Teraspace storage-enabled program = 
[ 1 | A2 |CHARGS) [Reserved = ~~~SSOSOSCS 
[Program statistics information 
[| 220 [ DC Snes [Minimum number of parameters 
CE BNR Pa 
[ 232 |[ Es ee i 
[ 244 | F4 eee Rankerof Mt nasties ————— 
SS ee 
[253 | FD |CHARG4)  |Compileridentification ~=~~SOS~*S 
| 267 | 10B |CHAR(@) — [Earliestrelease programcanrun 
[| 273 [ 111 |CHAR(IO) — Sortsequencetablename = 
| 303 [ 12F |CHAR() ~— |Progamdomain 9 = —— 
[| 304 [ 130 |CHAR() ~— |Conversionrequired = 
| 305 [| 131 |[CHAR(@0) [Reserved = 
Program performance information 

| 325 | 145 |CHAR() ~— [Optimization 
| 327 | 147 |CHAR() [Update program automatic storage area (PASA) 


| 330 | 14A |CHARGS) [Reserved ~~~~SCSCS 
| 407 | 197 |CHARG)  |Allowupdate =~ ~~~—~SCS 
| 408 | 198 |BINARY@) [ProgramCCSID.——~—~S~SCS 
| 412 | 19C |BINARYG@) [Number ofmodules —~—~—~—S~S*S 
| 448 | 1CO |CHARG)  |Storagemodel) ~~~~~SCSCS~S~S 
| 449 [ICI |CHAR@7) [Reserved ~~~SCS 


PGMI0200 Format 


The following information is returned for the PGMI0200 format. Some of the fields returned are blank or 
zero if they do not apply to the type of program specified. For detailed descriptions of the fields in the table, 
see Field Descriptions. 


| Offset 
| Dec Hex /Type Field 


[| 0 [ 0 |BINARY(4) [Bytesreturned = = = 
[| 4 [| 4  |BINARY(@)  [Bytesavailable = 
Program creation information 

[ 8 [ 8 |CHAR(O) ~~ [Progamname = = = = 
[18 | 12 |CHARGO)  |Programlibraryname—~=~CS*S 
| 28 | 1C |CHARO)  [Programowner = = 
| 38 [ 26 |CHAR(IO) ~— |Programattribute = 


| 71 | 47 |CHARCO) [Source filelibraryname == 
[ 81 [| 51 |CHAR(O) — Source filemembername == 
| 91 [| 5B  |CHAR(3) [Source file updated date and time = 
| 104 | 68 |CHAR() — |Observableinformation == 
| 105 [ 69 |CHAR(1) ~~ [Userprofileoption = 
[107 | 6B |CHARG)  |Logcommands = ~SO~C~S*~*~CS 
[ 108 [ 6C |CHAR() ~~ |AllowRTVCLSRC 
| 109 [ 6D |CHAR() ~~ |Fixdecimaldata == 
| 160 [ AO |CHAR() ~— [Typeofprogam == 
| 161 [ Al |CHAR() _ [Teraspace storage-enabled program = 
[ 16 | A2 |CHARGS) [Reserved = ~SCS~*~C“CS 
[Program statistics information 
[| 220 [ DC auto [Minimum number of parameters 
aE ERR Pe 
[ 232 [ E8 eee i 
[240 [FO BINARY@)— [Automat torage ae 
[ 244 | F4 nee [Number of MI instructions 
sr [EC [CRARG) —— Pepe 
[253 | FD |CHARG4)  |Compileridentification —~—~SCS~* 
| 267 | 10B |CHAR(@) — [Earliestrelease programcanrun 
[| 273 [| 111 |CHAR(IO) — Sortsequencetablename = 
| 303 [ 12F |CHAR() ~~ [Progamdomain 9 = —— 
[| 304 [ 130 |CHAR() ~— |Conversionrequired = 
| 305 [| 131 [CHAR(@20) [Reserved 
Program performance information 

[| 325 | 145 |CHAR() ~— [Optimization 
| 327 [ 147 |CHAR() [Update program automatic storage area (PASA) 
[| 328 [ 148 |CHAR() — {Clear program automatic storage area (PASA) 
| 329 | 149 |CHARC) ~~ [Pagingamount; = 
| 330 [ 144 |CHAR(I8) [Reserved 
[Progam SQLinformation =——esssssssss—sSSSSSS 
| 348 | 15C |BINARY(4) [Number of SQL statements = 
[| 352 [ 160 |CHAR(I8) — [Relationaldatabase = 


| 380 | 17C |CHARCO) [Allow copyofdata—~—~SCS*S 
| 390 | 186 |CHAR(O)  |CloseSQLeursor —~SCS~S~S 
| 410 | 19A |CHARCO)  [Dateformat—~—~—~—~SCS 
[ 420 | I1A4 |CHARG)  [Dateseparator ~~~SCS 
[432 | 1B0 |CHARGO) [Delay PREPARE ——~—SCSCS~S 
[ si1_| IFF |CHARG) |Allowupdate ~~~SCSCSC<C;«SC;~*S! 
[512 | 200 |BINARYG@) [ProgramCCSID.——~—~—~SCSCSC<C<C;<C;CS; 
| 516 | 204 |BINARYG@) |Numberofmodules —~—~—~—~SCS~S 
[Continuation of program SQL information +~~SCS<S;<C;<C;~S~S*S 
[549 | 205 |CHAR(O) [SQL packagename ——~—~S~S~S~S~S 
[559 | 22F |CHARGO) [SQL package library name —~—~S~S~S~S~S~S~S~S 
| 579 | 243 |CHAR(0) |SQLsort sequence tablename ——~—S~S 
[589 | 24D |CHAR(0) _|SQLsom sequence table library name 
[599 | 257 |CHARGO)  |SQLlanguage identifier —~—~—~S~S~S~*S 
[ 619 | 268 |CHARG) [Reserved ~~~SCS 
| 620 | 26C |BINARYG) |SQUpathoffset~—~SCSCS 
| 624 | 270 |BINARY@) |SQUpathlengh ~~~~—~SCS*S 
| 028 | 274 |CHAR@) [Reserved SCS 


[732 | 2DC |CHARG)  |[Storagemodel ~~SCS*S*S 
[733 | 2DD |CHAR@7) [Reserved ~~~~SCS~S*S 


Program information through offsets 


| | [CHAR(*) [SQL path 


PGMI0300 Format 


The following information is returned for the PGMI0300 format. This format is valid only for ILE 
programs. If an OPM program is specified, no data is returned and an error is returned. For detailed 
descriptions of the fields in the table, see Field Descriptions. 


| Offset 
| Dec Hex /Type Field 


[| 0 | 0 J|BINARY(@) [Bytesreturned = = = 2 
[ 4 [ 4  |BINARY()  [Bytesavailable = = == 
ILE program size information 
[| 8 | 8 |CHARUO)  [Programmame = = = 
| 28 [| IC |BINARY() — |Currenttotal program size == 
| 32 | 20 |BINARY(4) [Maximumprogramsize = = 
| 36 [ 24 |BINARY(4)  |Currentnumberofmodules == 
| 40 [| 28 |BINARY(4)  [Maximumnumberof modules = = 
| 44 | 2C |BINARY() |Current number of service programs = 
| 48 [| 30 |BINARY(4) [Maximum number of service programs 
| 52 [| 34 |BINARY(4) |Current string directory size = 
| 56 | 38 |BINARY(4) [Maximum string directory size 
| 60 [| 3C |BINARY(4) |Current copyright string size = 
| 68 | 44 |BINARY() — |Current number of auxiliary storage segments 
| 72 [| 48 |BINARY(4) — [Maximum number of auxiliary storage segments 
| 76 [| 4C |BINARY(4) [Minimum static storage size = 
| 80 | 50 |BINARY(4) [Maximum static storage size 
BE ————e———————— 
LSS 2S ENS) iain sabe Sage Se tone __ 
| 9 [ 6 0 |BINARY(8) [Maximum static storage size - long 


Field Descriptions 


For more detailed information than that provided in the following field descriptions, refer to documentation 
for the command that was used to create the program. For information on non-SQL fields, this would 
normally be one of the following: 


e@ One of the create program (CRTxxxPGM) commands described in the programmer's guide for the 
language, identified by the xxx in the command name. 


e The Create Program (CRTPGM) command. 


For information on SQL fields, (this would normally be a command of the form CRTSQLxxx) see DB2 
Universal Database for iSeries SQL Programming Concepts. The xxx in the command name identifies the 
base language (RPG, COBOL, and so on) of the program. 


Activation group attribute. The activation group attribute of this ILE program. 
Possible values are: 


*NEW A new activation group with the same name as the program name is created 
when this program is called. The program runs in this activation group. 


*DFTACTGRP The program uses one of two existing activation groups created when the 
process is started. One default activation group is reserved for system-state 
programs. The other default activation group is reserved for user-state 
programs. 


*CALLER The program runs in the activation group of the program from which it is 
called. 


activation group name The name of the activation group in which this program runs. If the activation 
group already exists when the program is called, the program runs in the 
existing activation group. If the activation group does not exist when the 
program is called, a new activation group is created and the program runs in it. 


Blank This program is an OPM program. 


2All creation data. Whether the ILE program has all creation data and if that data is observable or 
unobservable. All observable creation data is needed to re-create the program using the Change Program 
(CHGPGM) command. All creation data (either observable or unobservable) is needed to convert the 
program during restore. “ 


Possible values are: 


0 *NO. Not all of the creation data is present. The creation template of the ILE program object could 
be missing or at least one of the modules in this program does not have creation data. 


I *YES. The ILE program has all creation data and all of that data is observable. 


22 *UNOBS. The ILE program has all creation data but not all of that data is observable. * 


Allow blocking. Whether blocking is used to improve the performance of certain SQL statements. 
Possible values are: 


*NONE Blocking is not used. 


*READ Blocking is used for read-only data cursors when running COMMIT(*NONE) and there 
are no EXECUTE or EXECUTE IMMEDIATE statements. 


*ALLREAD Blocking is used for all read-only cursors when running COMMIT(*NONE) or 
COMMIT(*CHG). 


Blank The program does not contain SQL statements or it is an ILE program. 


Allow copy of data. Whether a copy of the data can be used in the implementation of an SQL query. 
Possible values are: 

*NO A copy of the data cannot be used. 

*YES A copy of the data can be used when needed. 

*OPTIMIZE The system determines whether a copy of the data is used for optimal performance. 


Blank The program does not contain SQL statements or it is an ILE program. 


Allow RTVCLSRC. The compiler allowed you to control this attribute through the ALWRTVSRC 
parameter if this program was created using the Create CL Program (CRTCLPGM) command. 


Possible values are: 
N_ Source for the CL program is not saved with the program (*NO). 


Y Source is saved (* YES). 


Source that is saved can be retrieved by using the Retrieve CL Source (RTVCLSRC) command. This 
information is blank if the program is not a CL program. 


Allow static storage reinitialization. Whether program static storage can be reinitialized. The values are 
valid for ILE programs only. 


Possible values are: 
Y Program static storage can be reinitialized. 


N_ Program static storage cannot be reinitialized. 


Allow bound *SRVPGM library name update. Whether the Update Program (UPDPGM) command is 
allowed to change the bound *SRVPGM library names on this program. The values are valid for ILE 
programs only. 

Possible values are: 


Y The UPDPGM command can specify a library name for the SRVPGMLIB parameter. 


N The UPDPGM command cannot specify a library name for the SRVPGMLIB parameter. 


Allow update. Whether the Update Program (UPDPGM) command is allowed on this program. The values 
are valid for ILE programs only. 


Possible values are: 


Y The UPDPGM command can be run on this program. 


N The UPDPGM command cannot be run on this program. 


Associated space size. The size (in bytes) of the associated space used by this program. 


Automatic storage size. The size (in bytes) of the automatic storage used by this program. This 
information is blank if the program is an ILE program. 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 


Clear program automatic storage area (PASA). The compiler may have allowed you to control this 
attribute through the GENOPT parameter of the command used to create the program. 


Possible values are: 
N Do not clear PASA storage (*NOCLRPASA). 
C Clear PASA storage (*CLRPASA). 


Blank The program is an ILE program. 


*NOCLRPASA reduces the time needed to call the program. However, if a program variable is referred to 
before it has been set, it may contain unpredictable data. 


*CLRPASA increases the time needed to call the program. However, it ensures that if a program variable is 
referred to before it has been set, it will contain binary zeros instead of unpredictable data. 


Close SQL cursor. Specifies when SQL cursors are implicitly closed and SQL-prepared statements are 
implicitly discarded. 


Possible values are: 


*ENDPGM When the program that contains the SQL statements ends. This value is valid for OPM 
programs only. 


*ENDSQL When the last program containing SQL statements ends. This value is valid for OPM 
programs only. 


*ENDJOB When the job ends. This value is valid for OPM programs only. 
*ENDMOD When the module ends. This value is valid for ILE programs only. 
*ENDACTGRP_ When the activation group is deleted. 


Blank The program does not contain SQL statements or it is an ILE program. 


Commitment control. The level of commitment control that was specified on the SQL precompile. 
Possible values are: 


*NONE No commitment control was specified on the SQL precompile. Uncommitted changes in other 
jobs can be seen. 


*CHG 


*CS 


*ALL 


Blank 


Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements are locked until the end of the unit of work (transaction). Updated, 
deleted, and inserted rows (records) are locked until the end of the unit of work. Uncommitted 
changes in other jobs can be seen. 


Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements are locked until the end of the unit of work (transaction). Updated, 
deleted, and inserted rows (records) are locked until the end of the unit of work. A row 
(record) that is selected but not updated is locked until the next row (record) is selected. 
Uncommitted changes in other jobs cannot be seen. 


Objects referred to in SQL COMMENT ON, CREATE, DROP, GRANT, LABEL ON, and 
REVOKE statements are locked until the end of the unit of work (transaction). All rows 
selected, updated, deleted, and inserted are locked until the end of the unit of work. 
Uncommitted changes in other jobs cannot be seen. 


The program does not contain SQL statements or it is an ILE program. 


Compiler identification. The licensed program identifier, version, release, and modification level of the 
compiler. The field has a pppppppbVvRrMm format, where: 


ppppppp The licensed program identifier. 


b 
Vv 
Rr 


Mm 


A blank character. 
The character V is followed by a 1-character version number. 
The character R is followed by a 1-character release level. 


The character M is followed by a 1-character modification level. 


For programs created by the Create Program (QPRCRTPG) API, this field identifies the version of the 
operating system that the program was created under. 


The field may be blank if the program is created without going through a compilation process or if it is an 
ILE program. 


Connection method. The method used for establishing remote connections when running distributed 


programs. 


Special values that can be returned are: 


*RUW 


*DUW 


Blank 


Only one connection to a relational database is allowed. Consecutive CONNECT statements 
result in the previous connection being disconnected before a new connection is established. 


Connections to several relational databases are allowed. Consecutive CONNECT statements to 
additional relational databases do not result in disconnection from previous connects. SET 
CONNECTION can be used to switch between connections. Read-only connections may 
result. 


The program does not contain SQL statements or is an ILE program. 


Conversion required. Indicates whether the program has been converted to reduced instruction-set 
computer (RISC) format or if conversion is still required. 


Possible values are: 


0 Conversion is not required. The program has already been converted. 


ZI Conversion is required. 


Creation date and time. The date and time the program was created. The creation date and time field is in 
the CY YMMDDHHMMSS format as follows: 


C Century, where 0 indicates years 19xx and 1 indicates years 20xx. 
YY Year 

MM _ Month 

DD Day 

HH Hour 

MM _ Minute 

SS Second 


Current copyright string size. The ILE program's copyright string size. 


Current number of auxiliary storage segments. The number of auxiliary storage segments in this ILE 
program. 


Current number of modules. The number of modules bound into this ILE program. 

Current number of service programs. The number of service programs bound to this ILE program. 
Current string directory size. The ILE program's string directory size. 

Current total program size. The total size of the ILE program, in kilobytes. 


Date format. The format used when accessing date-result columns through SQL. All output date fields are 
returned in this format. For input date strings, the value you specify is used to determine whether the date is 
a valid format. This information is blank if the program does not contain SQL statements or if it is an ILE 
program. 


Possible values are: 
*USA — USA format (mm/dd/yyyy). 
*ISO International Standards Organization format (yyyy-mm-dd). 
*EUR — European format (dd.mm.yyyy). 
*JIS Japanese Industrial Standard Christian Era (yvyyy-mm-dd). 
*MDY Month/day/year format (mm/dd/yy). 
*DMY  Day/month/year format (dd/mm/yy). 
*YMD _ = Year/month/day format (yy/mm/dd). 
*JUL — Julian format (a numeric value from 1 to 365). 


blank The program does not contain SQL statements, or it is an ILE program. 


Date separator. The separator used when accessing date-result columns. This information is blank if the 
program does not contain SQL statements or if it is an ILE program. However, the number of SQL 
statements field should be checked to determine if the program contains SQL statements. This is because a 
blank may be specified as a separator value. 


Default collection name. The collection name used for the unqualified names of tables, views, indexes, 
and SQL packages. 


Possible values are: 
*NONE There is no default collection name. 


Blank The program does not contain SQL statements or it is an ILE program. 


Delay PREPARE. Whether SQL prepare processing can be delayed until the statement is actually used. 
Possible values are: 

*YES Prepare processing can be delayed. 

*NO Prepare processing cannot be delayed. 


Blank The program does not contain SQL statements or it is an ILE program. 


Dynamic user profile. The user profile used for dynamic SQL statements. 
The following special values can be returned: 


*USER Local dynamic SQL statements are run under the profile of the programs user. Distributed 
dynamic SQL statements are run under the profile of the SQL package's user. 


*OWNER Local dynamic SQL statements are run under the profile of the programs owner. Distributed 
dynamic SQL statements are run under the profile of the SQL package's owner. 


Blank The program does not contain SQL statements or it is an ILE program. 


Earliest release program can run. The version, release, and modification level of the earliest release the 
program is allowed to run on. The compiler may have allowed you to control this through the TGTRLS 
parameter of the command used to create the program. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr The character R is followed by a 1-character release level. 


Mm __ The character M is followed by a 1-character modification level. 


Fix decimal data. Whether decimal data that is not valid is corrected or an error is signaled. If the 
System/36 environment is loaded on your system, you can control this attribute through the fix decimal data 
(FIXDECDTA) parameter of the CRTS36CBL or CRTS36RPG command. 
Possible values are: 

N An error is signaled to the program without correcting the data that is not valid (*NO). 

Y Decimal data that is not valid is corrected (* YES). 


Blank The program is an ILE program. 


Language identifier. Returns the 3-character language identifier used when the program was compiled. 
This information is blank if the module does not contain any language identification information. 


The following special value can also be returned: 


*JOBRUN The language identifier associated with the job at the time the program is run. 


Log commands. The value specified for the LOG parameter of the CRTCLPGM command. This field is 
meaningful only if the program is a CL program. The possible values are N (*NO), Y (YES), and J 
(*JOB). This information is blank if the program is not a CL program. 

Maximum copyright string size. The maximum size of the copyright string in an ILE program. 


Maximum number of auxiliary storage segments. The maximum number of auxiliary storage segments 
an ILE program can have. 


Maximum number of modules. The maximum number of modules that can be bound into an ILE 
program. 


Maximum number of parameters. The maximum number of parameters that may be received by the 
program when it is called. A value of -1 is returned if the program is not observable. 


Maximum number of service programs. The maximum number of service programs that can be bound to 
an ILE program. 


Maximum program size. The maximum size that an ILE program can be, in kilobytes. 


Maximum static storage size. The maximum static storage size (in bytes) that this program may need in 
order to run. 4*A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In 
this case, the maximum static storage size - long field should be used instead. 


Maximum static storage size - long. The maximum static storage size in bytes that this program may need 
in order to run. 


Maximum string directory size. The maximum size that the string directory can be in an ILE program. 


Minimum number of parameters. The minimum number of parameters that is to be received by the 
program when it is called. A value of -1 is returned if the program is not observable. 


Minimum static storage size. The minimum static storage size in bytes that this program needs in order to 
run. 2*A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In this case, 
the minimum static storage size - long field should be used instead. 


Minimum static storage size - long. The minimum static storage size in bytes that this program needs in 
order to run. * 


Naming convention. The convention used for naming objects in SQL statements. 
Possible values are: 

*SQL The SQL naming convention is used. 

*SYS The system naming convention is used. 


Blank The module does not contain SQL statements or it is an ILE program. 


Number of copyrights. The number of copyrights in this ILE program. This field is zero if the program is 
an OPM program. Do not assume that a value of zero indicates that the program is an OPM program. ILE 

programs may not have any copyrights, so this value could be zero for an ILE program. Check the type of 
program field to determine whether the program is an OPM program or an ILE program. 


Number of MI instructions. The number of machine interface (MI) instructions used by this program. A 
value of -1 is returned if the program is not observable. This information is zero if the program is an ILE 
program. 


Number of MI ODT entries. The number of ODT (object definition table) entries for the program. This is 
the number of program objects declared by the compiler. Program objects include variables, constants, 
labels, operand lists, and exception descriptions. Typically, one or more ODT entries are used for each 
variable, constant, and label in your program. Some are used by the compiler for internal purposes. The 
number of internal ODT entries varies depending on the size and complexity of the program. There is a 
limit of 32 767 ODT entries in a program. A value of -1 is returned if the program is not observable. This 
information is zero if the program is an ILE program. 


Number of modules. The number of modules bound into this program. This information is zero if the 
program is an OPM program. 


Number of service programs. The number of service programs bound to this program. This information is 
zero if the program is an OPM program. Do not assume that a value of zero indicates that the program is an 
OPM program. ILE programs may not have any service programs bound to them, so this value could be 
zero for an ILE program. Check the type of program field to determine whether the program is an OPM 
program or an ILE program. 


Number of SQL statements. The number of SQL statements contained in the program. This value is zero 
if the program does not contain SQL statements or if it is an ILE program. 


Number of unresolved references. The number of symbols that could not be resolved at Create Program 
(CRTPGM) command time. This information is always zero if the program is an OPM program. If this is 
an ILE program, and if all references were resolved at the time the program was created, this value for this 
field could be zero. 


Observable information. Whether the OPM program contains creation data and if that data is observable 
or unobservable. All observable creation data is needed to re-create the program using CHGPGM. All 
creation data (either observable or unobservable) is needed to convert the program during restore. 
Possible values are: 

A *ALL. The program has all creation data and that data is observable. 

N *NONE. The program does not have all creation data. 

2*U — *UNOBS. The program has all creation data but not all of that data is observable. 


Blank The program is an ILE program. 


The observable information for most programs may be removed by using the remove observability 
(RMVOBS) parameter on the Change Program (CHGPGM) command. 


Observable information compressed. Whether the observable information associated with the program is 
compressed. 


Possible values are: 


Y The observable information is compressed. 


N The observable information is not compressed. 


Blank The program is an OPM program. 


Optimization. Indicates what was specified on the OPTIMIZE parameter when the program was created or 
changed. 


Possible values are: 
N *NOOPTIMIZE was specified. 
O *OPTIMIZE was specified. 


Blank The program is an ILE program. 


Paging amount. The compiler may have allowed you to control this attribute through the GENOPT 
parameter of the command used to create the program. 


Possible values are: 
N_ Page the program one page at a time (*NOBLOCK). 
B_ Page the program in eight-page blocks (*BLOCK). 


*BLOCK gives better performance in most situations. It is likely that more than one page in the block is 
referred to before being replaced by some other paging occurring in the storage pool. 


*NOBLOCK can give better performance if the other pages that would have been brought in as a block are 
unlikely to be referred to before being replaced by some other paging. 


Paging pool. The paging pool used for the program object. The compiler may have allowed you to control 
this attribute through the GENOPT parameter of the command used to create the program. 


The values returned are: 
U_ Use the user pool (*USER). 
B_ Use the base pool (*BASE). 


M_ Use the machine pool (*MACHINE). 


*USER is used by most system programs and all user programs, unless GENOPT(*MACHINE) is 
specified. 


*BASE is used by certain system programs to avoid disturbing the user pool when they need to be paged in. 
These programs are not used frequently enough to belong in the machine pool. This value will only appear 
for OPM programs. 


*MACHINE is used by a small number of system programs that are so highly used that their pages should 
remain almost constantly in main storage. The machine pool is intended to be a stable, low paging pool. If 
user programs page in the machine pool, there may be contention for main storage between system and user 
programs. This may adversely affect system performance and response times. To prevent paging 
contention, increase the QMCHPOOL system value with the Change System Value (CHGSYSVAL) 
command. 


Profiling data. Specifies the profiling data attribute for this ILE program. 


Possible values are: 
*NOCOL The collection of profiling data is not enabled and profiling data is not applied. 


*COL The collection of profiling data is enabled for at least one module bound into this ILE 
program. Any applied profiling data has been removed. The QBNLPGMI API, format 
PGMLO100, can be used to determine if a module bound into this ILE program is 
enabled to collect profiling data. 


*APYBLKORD Block order profiling data has been applied to at least one module bound into this ILE 
program. The QBNLPGMI API, format PGMLO100, can be used to determine if a 
module bound into this ILE program has block order profiling data applied. 

*APYPRCORD Procedure order profiling data has been applied to this ILE program. 

*APYALL Block order and procedure order profiling data has been applied to this ILE program. 


Blank This program is an OPM program. 


Program attribute. The language the program is written in. (For example, the value is CLP for a CL 
program, and the value is RPG for an RPG program). This field can be blank. (For example, the program 
was created by the Create Program (QPRCRTPG) API or the program is created by a compilation process 
internal to IBM). 


Program CCSID. The coded character set identifier (CCSID) for this ILE program. This is 65535 for ILE 
programs. This information is zero if the program is an OPM program. 


Program domain. The domain of the program. 
Possible values are: 
S The program can be called by system-state programs. 


U_ The program can be called by user- or system-state programs. 


Program entry procedure module. The module name that contains the program entry procedure for this 
program. This information is blank if the program is an OPM program. 


Program entry procedure module library. The library name that contained the module that contained the 
program entry procedure for this program when the bind was done. This information is blank if the program 
is an OPM program. 
Program library name. The name of the library containing the program. 
Program name. The name of the program. 
Program owner. The name of the program owner's user profile. 
Program size. The size (in bytes) of this program. 
Program state. The state of the program. 
Possible values are: 
I The program runs under (inherits) the same state as its caller. 


S The program runs as a system-state program. 


U_ The program runs as a user-state program. 


Relational database. The default relational database that was specified on the SQL precompile. A 
nonblank value other than *LOCAL specifies the name of the relational database to be resolved through the 
relational database directory. 

The following special values can be returned: 


*LOCAL The program can only access data on the local system. 


Blank The program does not contain SQL statements or it is an ILE program. 


Release program created for. This is the release specified on the target release (TGTRLS) parameter of 
the Create Program (CRTPGM) command. The value specified for the TGTRLS parameter can affect the 
earliest release value on which the program can run. 


Release program created on. The version, release, and modification level of the operating system on 
which the program was created. 


Reserved. An ignored field. 


Run-time information compressed. Whether the run-time information associated with the program is 
compressed. 


Possible values are: 
Y The run-time information is compressed. 
N The run-time information is not compressed. 


Blank The program is an OPM program. 


Shared activation group. Whether the program runs in a shared activation group. 
Y The activation group is shared. 


N_ The activation group is not shared. 


Sort sequence table library name. The name of the library the sort sequence table is in. 


This information is blank if the program does not contain any sort sequence information or a special value 
was returned for the sort sequence table name. 


The following special values can be returned: 
*CURLIB The job's current library 


*LIBL The library list 


Sort sequence table name. The name of the sort sequence table used when the program was compiled. 
This does not apply to SQL statements in the program. 


The following special values can be returned: 


*HEX No sort sequence is used. 


*JOBRUN The sort sequence value that is associated with the job at the time the program runs. 
*LANGIDSHR _ The shared sort sequence for the language identifier is used. 

*LANGIDUNQ The unique sort sequence for the language identifier is used. 

Blank The program does not contain SQL statements or it is an ILE program. 


Note: This sort sequence table does not apply to SQL statements. 


Source file library name. The name of the library that contains the source file used to create the program. 
The field is blank if a source file was not used to create the program or if it is an ILE program. 


Source file member name. The name of the member in the source file. The field is blank if a source file 
was not used to create the program or if it is an ILE program. 


Source file name. The name of the source file used to create the program. The field is blank if a source file 
was not used to create the program or if it is an ILE program. 


Source file updated date and time. The date and time the member in the source file was last updated. The 
field is in the same format as the creation time and date. The field is blank if a source file was not used to 
create the program or if it is an ILE program. 


SQL package library name. The name of the library the SQL package is in. 


SQL package name. The name of the SQL package created on the relational database specified on the 
RDB parameter of the command that created this program. 


*NONE This is not a distributed program. 


Blank The program does not contain SQL statements or it is an ILE program. 


SQL path. The list of libraries used during resolution of functions, procedures, and data types within SQL 
statements. The list is in the form of repeating library names, each surrounded by double quotes and 
separated by commas. 


SQL path length. The length, in bytes, of the SQL path. 


SQL path offset. The offset, in bytes, from the beginning of this format definition to the beginning of the 
SQL path. 


SQL sort language identifier. The 3-character language identifier used when the program was compiled. 
This information is blank if the program does not contain any language identification information. 


The following possible special value can be returned: 


*JOBRUN The language identifier is the LANGID associated with the job at the time the program is 
run. 


SQL sort sequence table name. The SQL sort sequence table returns the SQL sort sequence table name 
used when the program was compiled. This information is blank if the program does not contain any SQL 
sort sequence information or if this is an ILE program. 


The following special values can be returned: 


*HEX No SQL sort sequence is used for the SQL statements. 


*JOBRUN The SQL sort sequence is the SRTSEQ value associated with the job at the time the 
SQL statements within the program are run. 


*LANGIDSHR _ The shared SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


*LANGIDUNQ The unique SQL sort sequence for the language identifier (LANGID) is used for the 
SQL statements. 


SQL sort sequence table library name. The name of the library the SQL sort sequence table is in. This 
information is blank if the program does not contain any SQL sort sequence information or a special value 
was returned for the SQL sort sequence table name. 


The following special values can be returned: 
*CURLIB The job's current library 


*LIBL The library list 


Static storage size. For OPM programs this is the size (in bytes) of the static storage used by the program. 
For ILE programs this is the maximum amount of static storage (in bytes) that may be needed to run the 
program. #*A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In this 
case, the maximum static storage size - long field should be used instead. The maximum static storage size - 
long field is available from the PGMI0300 format. OPM programs will always have less than 4 gigabytes of 
static storage. 


Storage model. Where the automatic and static storage for this program is allocated at run time. 
The following values can be returned: 

0 *SNGLVL Automatic and static storage are allocated from single-level storage. 

1 *TERASPACE Automatic and static storage are allocated from teraspace. 


2 *INHERIT Automatic and static storage are allocated from either single-level storage or 
teraspace, depending on the activation. 


Teraspace storage enabled modules. The teraspace storage capability of the modules bound to this 
program. 


Possible values are: 
‘00"X No modules bound to this program are teraspace storage enabled. 


'80"X_ One or more modules bound to this program are teraspace storage enabled. The *PEP module, 
however, is not teraspace storage enabled. 


'CO'X The *PEP module is teraspace storage enabled, and there may be more modules bound to this 
program that are teraspace storage enabled. 


"EO'X All modules bound to this program are teraspace storage enabled. 


Teraspace storage enabled program. The teraspace storage capability of an OPM program. A program 
must be teraspace storage enabled to access teraspace storage. 


Possible values are: 


0 This program is not teraspace storage enabled. 


I This program is teraspace storage enabled. 


Text description. The user text, if any, used to briefly describe the program and its function. 


Time format. The format used when accessing time-result columns through SQL. All output time fields are 
returned in this format. 


Possible values are: 
*USA USA format (hh:mm a.m. or p.m.). 
*ISO International Standards Organization format (hh.mm.ss). 
*EUR European format (hh.mm.ss). 
*JIS Japanese Industrial Standard Christian Era (hh.mm.ss). 
*HMS _ Hours/minutes/seconds format (hh:mm:ss). 


Blank The program does not contain SQL statements or it is an ILE program. 


Time separator. The separator used when accessing time-result columns. This information is blank if the 
program does not contain SQL statements or if it is an ILE program. However, the number of SQL 
statements is checked to determine if the program contains SQL statements. This is because a blank may be 
specified as a separator value. 

Type of program. Whether the program is an ILE program or an OPM program. 

Possible values are: 


Blank OPM program 


B ILE program 


Update program automatic storage area (PASA). The compiler may have allowed you to control this 
attribute through the GENOPT parameter of the command used to create the program. This information is 
blank if the program is an ILE program. 

Possible values are: 


N_ Do not update internal PASA stack information (*NOUPDPASA). 
U_ Update internal PASA stack information (*UPDPASA). 


*NOUPDPASA reduces the time needed to call the program. 


*UPDPASA increases the time needed to call the program but is used by some system programs that are 
dependent on updates of internal PASA stack information. 


Use adopted authority. The value specified for the USEADPAUT option on the command used to change 
the program. 


Possible values are: 


Y Uses program adopted authority from previous call levels when this program is running (* YES). 


N_ Does not use program adopted authority from previous call levels when this program is running 


(*NO). 


User profile option. The value specified for the USRPRF option on the command used to create the 


program. 


Possible values are: 


U_ The program runs under the current user's user profile (*USER). 


O_ The program runs under both the current user's and the owner's user profiles (*OWNER). 


Error Messages 


Message ID 
CPF2150 E 
CPF2151E 
CPF24B4 E 
CPF3CF1 E 
CPF3C19 E 
CPF3C21 E 
CPF3C24 E 
CPF3C90 E 
CPFSCF5 E 
CPF8122 E 
CPF8123 E 
CPF8129 E 
CPF9801 E 
CPF9802 E 
CPF9803 E 
CPF9806 E 
CPF9807 E 
CPF9808 E 
CPF9810 E 
CPF9811 E 


Error Message Text 

Object information function failed. 

Operation failed for &2 in &1 type *&3. 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error occurred with receiver variable specified. 
Format name &1 is not valid. 

Length of the receiver variable is not valid. 

Literal value cannot be changed. 

&1 in library &2 not bound program. 

&8 damage on library &4. 

Damage on object information for library &4. 
Program &4 in &9 damaged. 

Object &2 in library &3 not found. 

Not authorized to object &2 in &3. 

Cannot allocate object &2 in library &3. 

Cannot perform function for object &2 in library &3. 
One or more libraries in library list deleted. 

Cannot allocate one or more libraries on library list. 
Library &1 not found. 


Program &1 in library &2 not found. 


CPF9820 E 
CPF9821 E 
CPF9830 E 
CPF9872 E 


Not authorized to use library &1. 
Not authorized to program &1 in library &2. 
Cannot assign library &1. 


Program or service program &1 in library &2 ended. Reason code &3. 


API introduced: V2R2 


Top | Program and CL Command APIs | APIs by category 


Retrieve Prompt Override (QPTRTVPO) API 


Required Parameter Group: 


Receiver Variable Char(*) 
Length of receiver variable Binary(4) 
Receiver variable format name Char(8) 
Command string Char(*) 


Length of command string Binary(4) 
Error code Char(*) 


Default Public Authority: *USE 


Threadsafe: Yes. See Usage Notes for prompt override program considerations. 


The Retrieve Prompt Override (QPTRTVPO) API calls the prompt override program for a specified 
command and returns the prompt override command string from the prompt override program. 


Authorities and Locks 


Command 
*USE 
Prompt override program 
*EXECUTE 
Library 
*EXECUTE 


Required Parameter Group 


Receiver variable 
OUTPUT; CHAR(*) 
The variable that is to receive the information requested. The minimum size of this area is 8 bytes. 
You can specify the size of this area to be smaller than the format requested as long as you specify 


the length parameter correctly. The API will not attempt to return more data than the receiver can 
hold. 


Length of receiver variable 
INPUT; BINARY(4) 
The length of the receiver variable. If this value is larger than the actual size of the receiver 
variable, the results may not be predictable. The minimum length is 8 bytes. 


Receiver variable format name 


INPUT; CHAR(8) 


The format of the receiver variable. RTVP0100 is the only valid value. For more information, see 
RTVPO0O100 Format. 


Command string 
INPUT; CHAR(*) 


The command string containing the command name and the key parameter values. The command 
name may be library-qualified. The command string should be in the format in which it would be 
entered on a command line. Values must be specified for all key parameters. 


Length of command string 
INPUT; BINARY(4) 


The length of the command string. Valid valids are between 1 and 32 702. The length can include 
trailing blanks but must not include trailing null characters. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


RTVP0100 Format 


The RTVPO0100 format includes information on the contents of the receiver variable. The following table 
shows how this information is organized. For detailed descriptions of the fields in the list, see Field 


Descriptions. 


[Offset 
= Hex |Type Field 


Field Descriptions 


Bytes available. The length of all data available for the requested format. All available data is returned if 
enough space is provided. 


Bytes returned. The length of all data actually returned. If the receiver variable is not large enough to hold 
the data, no other data is returned and this value is less than the bytes available. 


Length of prompt override command string. The length of the prompt override command string returned 
by the API. If the prompt override program completed normally, but did not return a command string, this 


will be 0. If the prompt override program ended in error, this will be -1. 


Offset to prompt override command string. Offset to the first byte of the prompt override command 
string. 


Prompt override command string. The command string returned by the prompt override program. The 
command string will not include the command name, the key parameters, or any other parameters not 
specified by the prompt override program. If the receiver is not large enough to hold the entire command 
string, the command string will not be returned, and the Bytes available field will have the size of the 
receiver value required for the command string. 


Prompt override program library name. The name of the library in which the prompt override program 
was found. 


Prompt override program name. The name of the prompt override program that was called to supply the 
prompt override command string. 


Usage Notes 


While this API is threadsafe, it should not be used to call a prompt override program that is not threadsafe 
in a multithreaded job. 


Error Messages 


CPEFO0001 E Error found on &1 command. 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CIDE Length specified in parameter &1 not valid. 
CPF3C19 E Error occurred with receiver variable specified. 
CPF3C20 E Error found by program &1. 

CPF3C21 E Format name &1 is not valid. 

CPF3C24 E Length of the receiver variable is not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPF6802 E Error calling prompt override program. 
CPF6803 E Required key parameter not specified. 
CPF6804 E No prompt override program for command. 
CPF680A E Current values could not be retrieved. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API introduced: V5R1 


Top | Program and CL Command APIs | APIs by category 


Retrieve Service Program Information 
(QBNRSPGM) API 


Required Parameter Group: 


Receiver variable Char(*) 
Length of receiver variable Binary(4) 
Format name Char(8) 
Qualified service program name Char(20) 
Error Code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The Retrieve Service Program Information (QBNRSPGM) API lets you retrieve service program 
information and place it into a single variable in the calling program. The amount of information returned is 
limited to the size of the variable. This information is similar to the information returned using the Display 
Service Program (DSPSRVPGM) command. 
You can use the QBNRSPGM API to retrieve the following: 

e Service program creation information 

e Service program statistics 

e Service program performance information 


e Service program size information 


Authorities and Locks 


Library Authority 
*EXECUTE 
Service Program Authority (see note) 
*READ 
Service Program Lock 
*SHRRD 
Note: You must have *USE service program authority to retrieve the following fields in the SPGIO100 
format: 
e Export source file name 
e Export source file library name 


e Export source file member name 


If you attempt to retrieve these fields with *READ service program authority, they are set to blanks. All 


other fields in the SPGI0O100 format require *READ service program authority. 


Required Parameter Group 
Receiver variable 
OUTPUT; CHAR(*) 


The variable that is to receive the information requested. The minimum size for this area is 8 bytes. 
You can specify the size of this area to be smaller than the format requested if you specify the 
length of receiver variable parameter correctly. As a result, the API returns only the data that the 
area can hold. 


Length of receiver variable 
INPUT; BINARY(4) 


The length of the receiver variable. If this value is larger than the actual size of the receiver 
variable, the results may not be predictable. The minimum value is 8. 


Format name 
INPUT; CHAR(8) 


The content and format of the information returned for the service program. 
The possible format names are: 
SPGIOJOO Basic service program information. 


SPGIO200 Service program size information. 


Qualified service program name 
INPUT; CHAR(20) 


The first 10 characters contain the service program name. The second 10 characters contain the 
name of the library where the service program is located. 


You can use these special values for the library name: 
*CURLIB The job's current library 


*LIBL The library list 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


SPGI0O100 Format 


The following information is returned for the SPGIO100 format. See Authorities and Locks for the authority 
needed regarding specific fields. For detailed descriptions of the fields in the table, see Field Descriptions. 


| Offset 
eae HE c | Hex |Type Field 


| 320 | 140 |CHAR(@) [Release service programcreatedon 
| 326 | 146 |CHAR(@) [Earliest release service programcanrun 
| 332 [ 14C |CHAR() [Release service program created for 
[| 338 | 152 [CHAR() [Allow static storage reinitialization = 
| 340 [ 154 |CHAR() ~— fAllcreationdata = 
| 341 [| 155 [CHAR@1) ~~ [Reserved 
Service program performance information 

[ 432 [| 1B0 |CHARC) — [Pagingpoolh 
| 433 [| IB] [CHAR() — [Pagingamount; = 


SPGI0200 Format 


The following information is returned for the SPGIO200 format. For detailed descriptions of the fields in 
the table, see Field Descriptions. 


| Offset 
| Dec | Hex /Type Field 


[ 0 [ 0 JBINARY(4) [Bytesreturned = = 
| 4 [| 4  JBINARY(@)  [Bytesavailable = 9 = 
Service program size information 
| 18 [| 12 |CHAR(O0) [Service program libraryname = 
| 28 | 1C |BINARY(4)  |Currenttotal service program size 
| 32 [ 20 |BINARY(4)  [Maximumservice program size = 
| 36 | 24 |BINARY(4)  |Currentnumberofmodules = = == 
| 40 | 28 |BINARY(4)  [Maximumnumberofmodules = 
| 44 [ 2C |BINARY(4) |Current number of service programs = 
| 48 [| 30 |BINARY(4) — [Maximum number of service programs = 
| 52 | 34 |BINARY(4)  |Currentstring directory size 
| 56 [ 38 |BINARY(4) [Maximum string directory size 
| 60 | 3C |BINARY(4) |Current copyright string size = 
| 64 | 40 |BINARY(4) [Maximum copyright string size = 
| 68 [| 44 |BINARY(4) |Current number of auxiliary storage segments 
Ce BS |e 
[BINARY(4) |Current number of program procedure exports 


mi 4C 
BINARY(4) Maximum number of program procedure 
exports 


[84 | 54 |BINARY@) |Current number of program data exports 


| 100 64 |BINARY(4) Minimum static storage size 

| 104 68  |BINARY(4) Maximum Static storage size 

| 2108 | 6C  |CHAR(4) Reserved 

| 112 70  |BINARY(8) Minimum static storage size - long 

| 120 78 |BINARY(8) Maximum static storage size - long « 


Field Descriptions 


For more detailed information than that provided in the following field descriptions, refer to the online help 
for the Create Service Program (CRTSRVPGM) command. 


Activation group attribute. The activation group attribute of this service program. 
The possible values are: 


*CALLER The service program runs in the activation group of the program from which it 
is called. 


activation group name The name of the activation group in which this service program runs. If the 
activation group already exists when the service program is called, the service 
program runs in the existing activation group. If the activation group does not 
exist when the service program is called, a new activation group is created in 
which the service program runs. 


2>All creation data. Whether the ILE service program has all creation data and if that data is observable or 
unobservable. All observable creation data is needed to re-create the service program using the Change 
Service Program (CHGSRVPGM) command. All creation data (either observable or unobservable) is 
needed to convert the service program during restore. 


Possible values are: 


0 *NO. Not all of the creation data is present. The creation template of the service program object 
could be missing or at least one of the modules in this service program does not have creation data. 
The Display Service Program (DSPSRVPGM) command with *MODULE specified as the value 
for the DETAIL parameter can be used to see whether a module has creation data. 

I *YES. The ILE service program has all creation data and all of that data is observable. 


22 *UNOBS. The ILE service program has all creation data but not all of that data is observable. 


Allow static storage reinitialization. Whether service program static storage can be reinitialized. 
The possible values are: 
Y Program static storage can be reinitialized. 


N_ Program static storage cannot be reinitialized. 


Allow bound *SRVPGM library name update. Whether the Update Service Program (UPDSRVPGM) 
command is allowed to change the bound *SRVPGM library names on this service program. 


Possible values are: 
Y The UPDSRVPGM command can specify a library name for the SRVPGMLIB parameter. 


N VPGM command cannot specify a library name for the SRVPGMLIB parameter. 


Allow update. Whether the Update Service Program (UPDSRVPGM) command is allowed on this service 
program. 


Possible values are: 
Y The UPDSRVPGM command can be run on this service program. 


N The UPDSRVPGM command cannot be run on this service program. 


Associated space size. The size (in bytes) of the associated space used by this service program. 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 


Conversion required. Indicates whether the service program has been converted to reduced instruction-set 
computer (RISC) format or if conversion is still required. The 


Possible values are: 
O Conversion is not required. The service program has been converted. 


ZI Conversion is required. 


Creation date and time. The date and time the service program was created. The creation date and time 
field is in the CY YMMDDHHMMSS format as follows: 


C Century, where 0 indicates years 19xx and 1 indicates years 20xx. 
YY Year 

MM _ Month 

DD Day 

HH Hour 

MM _ Minute 

SS Second 


Current copyright string size. The size of the service program's copyright string. 
Current export signature. The current export signature of this service program. 


Current number of auxiliary storage segments. The number of auxiliary storage segments in this service 
program. 


Current number of modules. The number of modules bound into this service program. 


Current number of program data exports. The number of data items exported from this service program. 


Current number of program procedure exports. The number of procedures exported from this service 
program. 


Current number of service programs. The number of service programs bound to this service program. 
Current number of signatures. The number of signatures for this service program. 

Current string directory size. The service program's string directory size. 

Current total service program size. The total size of the service program, in kilobytes. 


Earliest release service program can run. The version, release, and modification level of the earliest 
release on which the service program is allowed to run. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


Export source file library name. The name of the library that contains the export source file. This may be 
blank if: 


e No export source file was specified on the CRTSRVPGM command. 
e You attempt to retrieve this field with a service program authority of “READ. A service program 
authority of *USE is required. 
Export source file member name. The name of the member in the export source file that was used to 
create this service program. This may be blank if: 
e No export source file was specified on the CRTSRVPGM command. 
e You attempt to retrieve this field with a service program authority of “READ. A service program 
authority of *USE is required. 
Export source file name. The name of the export source file that contains the export source file member. 
This may be blank if: 
e No export source file was specified on the CRTSRVPGM command. 
e You attempt to retrieve this field with a service program authority of “READ. A service program 
authority of *USE is required. 


Maximum copyright string size. The maximum size of the copyright string in a service program. 


Maximum number of auxiliary storage segments. The maximum number of auxiliary storage segments a 
service program can have. 


Maximum number of modules. The maximum number of modules that can be bound into a service 
program. 


Maximum number of program data exports. The maximum number of data items that can be exported 
by a service program. 


Maximum number of program procedure exports. The maximum number of procedures that can be 
exported by a service program. 


Maximum number of service programs. The maximum number of service programs that can be bound to 
a service program. 


Maximum number of signatures. The maximum number of signatures that can be in a service program. 
Maximum service program size. The maximum size of a service program, in kilobytes. 

Maximum static storage size. The maximum amount of static storage in bytes that may be needed to run 
the service program. #* A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is 


needed. In this case, the maximum static storage size - long field should be used instead. 


Maximum static storage size - long. The maximum amount of static storage in bytes that may be needed 
to run the service program. 


Maximum string directory size. The maximum size of the string directory in a service program, in bytes. 
Minimum static storage size. The minimum amount of static storage, in bytes, needed to run the service 
program. #* A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In this 


case, the minimum static storage size - long field should be used instead. 


Minimum static storage size - long. The minimum amount of static storage in bytes needed to run the 
service program. * 


Number of copyrights. The number of copyrights in this service program. 
Number of modules. The number of modules bound into this service program. 


Number of service programs. The number of service programs bound to this program. 


Number of unresolved references. The number of symbols that could not be resolved at Create Service 
Program (CRTSRVPGM) command time. This number could be zero if all references were resolved at the 
time the service program was created. 


Observable information compressed. Whether the observable information associated with the service 
program is compressed. 


The possible values are: 
Y The observable information is compressed. 


N_ The observable information is not compressed. 


Paging amount. The compiler may have allowed you to control this attribute through the GENOPT 
parameter of the CRTSRVPGM command. 


Possible values are: 
N_ Page the program one page at a time (*NOBLOCK). 


B_ Page the program in eight-page blocks (*BLOCK). 


*BLOCK gives better performance in most situations. It is likely that more than one page in the block is 
referred to before being replaced by other paging occurring in the storage pool. 


*NOBLOCK can give better performance if the other pages that would have been brought in as a block are 
unlikely to be referred to before being replaced by other paging. 


Paging pool. The paging pool used for the service program object. The compiler may have allowed you to 
control this attribute through the GENOPT parameter of the CRTSRVPGM command. 


The values returned are: 
U_ Use the user pool (*USER). 
M_ Use the machine pool (*MACHINE). 


*USER is used by most system service programs and all user service programs unless 
GENOPT(*MACHINE) is specified. 


*MACHINE is used by a few system service programs that are so highly used that their pages should 
remain almost constantly in main storage. The machine pool is intended to be a stable, low paging pool. If 
user service programs page in the machine pool, there may be contention for main storage between system 
and user service programs. This may adversely affect system performance and response times. To prevent 
paging contention, increase the QMCHPOOL system value with the Change System Value 
(CHGSYSVAL) command. 


Profiling data. The profiling data attribute for this service program. 
Possible values are: 
*NOCOL The collection of profiling data is not enabled and profiling data is not applied. 


*COL The collection of profiling data is enabled for at least one module bound into this 
service program. Any applied profiling data has been removed. The QBNLSPGM API, 
format SPGLO100, can be used to determine if a module bound into this service 
program is enabled to collect profiling data. 


*APYBLKORD  Block-order profiling data has been applied to at least one module bound into this 
service program. The QBNLSPGM API, format SPGLO100, can be used to determine 
if a module bound into this service program has block-order profiling data applied. 


*APYPRCORD  Procedure-order profiling data has been applied to this service program. 


*APYALL Block-order and procedure-order profiling data have been applied to this service 
program. 


Release service program created for. This is the release specified on the target release (TGTRLS) 
parameter of the Create Service Program (CRTSRVPGM) command. The value specified for the TGTRLS 
parameter can affect the earliest release value on which the program can run. 


Release service program created on. The version, release, and modification level of the operating system 
on which the service program was created. The field has a VvRrMm format, where: 


Vv _ The character V is followed by a 1-character version number. 
Rr — The character R is followed by a 1-character release level. 


Mm _ The character M is followed by a 1-character modification level. 


Reserved. An ignored field. 


Run-time information compressed. Whether the run-time information associated with the service 
program is compressed. 


Possible values are: 


Y_ The run-time information is compressed. 


N_ The run-time information is not compressed.The run-time information is not compressed. 


Service program attribute. The language the program is written in (for example, RPG.) 


Service program CCSID. The coded character set identifier (CCSID) for this service program. This is 
65535 for service programs. 


Service program domain. The domain of the service program. 
Possible values are: 
S The service program can be called by system-state programs. 


U_ The service program can be called by user- or system-state programs. 


Service program library name. The name of the library containing the service program. 
Service program name. The name of the service program. 
Service program owner. The name of the service program owner's user profile. 
Service program size. The size (in bytes) of this service program. 
Service program state. The state of the service program. 
Possible values are: 
I The service program runs under (inherits) the same state as its caller. 
S The service program can call user- or system-state programs. 


U_ The service program can call user-state programs. 


Shared activation group. Whether the service program runs in a shared activation group. 
Y The activation group is shared. 


N_ The activation group is not shared. 


Static storage size. The maximum amount of static storage in bytes that may be needed to run the service 
program. # A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In this 
case, the maximum static storage size - long field should be used. The maximum static storage size - long 
field is available from the SPGI0200 format. * 


Storage model. Where the automatic and static storage for this service program is allocated at run time. 
The following values can be returned: 

0 *SNGLVL Automatic and static storage are allocated from single-level storage. 

1 *TERASPACE Automatic and static storage are allocated from teraspace. 


2 *INHERIT Automatic and static storage are allocated from either single-level storage or 
teraspace, depending on the activation. 


Teraspace storage enabled modules. The teraspace storage capability of the modules bound to this service 


program. 
Possible values are: 
‘00'X No modules bound to this service program are teraspace storage enabled. 
‘8O'X One or more modules bound to this service program are teraspace storage enabled. 


‘AO'X All modules bound to this service program are teraspace storage enabled. 


Text description. The user text, if any, used to briefly describe the service program and its function. 


Use adopted authority. The value specified for the USEADPAUT option on the command used to change 
the service program. 


Possible values are: 


Y Uses program adopted authority from previous call levels when this service program is running 
(*YES). 


N_ Does not use program adopted authority from previous call levels when this service program is 
running (*NO). 


User profile. The value specified for the USRPRF option on the CRTSRVPGM command. 
Possible values are: 
U_ The service program runs under the current user's user profile (*USER). 


O_ The service program runs under both the current user's and the owner's user profiles (*OWNER). 


Error Messages 


Message ID Error Message Text 

CPF2150E Object information function failed. 
CPF2151E Operation failed for &2 in &1 type *&3. 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3C19 E Error occurred with receiver variable specified. 
CPF3C20 E Error found by program &1. 

CPF3C21E Format name &1 is not valid. 

CPF3C24 E Length of the receiver variable is not valid. 
CPF3C90 E Literal value cannot be changed. 


CPF8122 E &8 damage on library &4. 


CPF8123 E 
CPF813D E 
CPF9801 E 
CPF9802 E 
CPF9803 E 
CPF9806 E 
CPF9807 E 
CPF9808 E 
CPF9810 E 
CPF9811 E 
CPF9820 E 
CPF9821 E 
CPF9830 E 
CPF9872 E 


Damage on object information for library &4. 
Service program &4 in &9 damaged. 

Object &2 in library &3 not found. 

Not authorized to object &2 in &3. 

Cannot allocate object &2 in library &3. 

Cannot perform function for object &2 in library &3. 
One or more libraries in library list deleted. 

Cannot allocate one or more libraries on library list. 
Library &1 not found. 

Program &1 in library &2 not found. 

Not authorized to use library &1. 

Not authorized to program &1 in library &2. 


Cannot assign library &1. 


Program or service program &1 in library &2 ended. Reason code &3. 


API introduced: V2R3 


Top | Program and CL Command APIs | APIs by category 


Scan for String Pattern (QCLSCAN) API 


Required Parameter Group: 


Character string Char(*) 
Length of character string Packed(3,0) 
Starting position Packed(3,0) 
Character pattern Char(*) 
Length of character pattern Packed(3,0) 
Translate characters Char((1) 
Trim trailing blanks Char((1) 
Wildcard character Char(1) 
Character string result Packed(3,0) 


1 
2 
3 
4 
5 
6 
7 
8 
9 


Default Public Authority: *USE 


Threadsafe: No 


The Scan for String Pattern (QCLSCAN) API is used to scan a string of characters to see if the string 
contains a pattern. This function is similar to the scan function supported within source entry utility (SEU) 
and on the display presented by the Display Spooled File (DSPSPLF) command. In addition, the 
QCLSCAN API also allows you to specify a 1-byte character in the pattern that matches with any character 
in the string to be searched, and a start position, which allows you to search the same string more than once. 


A typical use of the QCLSCAN API is to allow the work station user to retrieve all records that contain a 
specified pattern. For example, if the database has records with book titles, the work station user may want 
to retrieve all those books with the pattern CHICAGO in the title. The work station user enters CHICAGO 
on the device display. The application program reads the database, calling the QCLSCAN API at least once 
for each record to test for the pattern. The application program only processes the records that pass the test 
for the pattern CHICAGO. 


Another alternative for this task is using the Open Query File (OPNQRYF) command. If you are searching 
an entire database member, the OPNQRYF command normally produces faster results. If you are searching 
a small subset of a member or the file is already open, QCLSCAN normally produces faster results. 


Scanning a field can require many lines of code in a high-level language and can cause a significant amount 
of overhead. Calling the QCLSCAN API and passing it a parameter list may be a simpler and faster way to 
do the scan. 


Required Parameter Group 


Character string 
INPUT;CHAR(*) 
A character field from 1 through 999 characters that contains the string to be scanned for the 
pattern. 


Length of character string 


INPUT;PACKED(3,0) 
The length of the string to be scanned. If this length is greater than the actual length of the string, 
unexpected results can occur. 

Starting position 
INPUT;PACKED(3,0) 
The position in the string where the scan is to start. The position must be greater than zero and not 
greater than the string length. Normally this value is 1. If the same string has multiple sets of 


patterns, this allows the string to remain the same while only the start position is varied to find the 
additional patterns. 


Character pattern 
INPUT:;CHAR(*) 


The pattern being scanned for. 
Length of character pattern 
INPUT;PACKED(3,0) 


The length of the pattern. If this length is greater than the actual length of the pattern, unexpected 
results can occur. 


Translate characters 
INPUT;CHAR(1) 


A variable that indicates to translate lowercase characters in the specified character string to 
uppercase characters. If this field contains a 1, the program translates lowercase characters of the 
string to uppercase before the scan using the coded character set identifier (CCSID) for the current 
job. If the translation cannot be done using the CCSID for the job, *CCSID37 is used. This does 
not change the user's data. Note that if 1 is specified and the pattern contains lowercase characters, 
a match never occurs. If 1 is specified, and the data to be searched contains noncharacter data (for 
example, packed or binary), unexpected results can occur. 

Trim trailing blanks 


INPUT;CHAR(1) 

A fixed-length pattern field filled (left-justified) by a variable number of characters. If this variable 

contains a 1, trailing blanks are trimmed from the end of the pattern before the scan is started. 
Wildcard character 

INPUT;CHAR(1) 

A variable that you can specify in the pattern, in positions that should not be tested when scanning 

for a match. When this character appears in the pattern, any character in the data is considered a 


match. A value of blank indicates that all characters of the pattern take part in the scan. If the 
wildcard character is the first character in the pattern, an error will occur. 


Character string result 
OUTPUT:PACKED(3,0) 


The value is returned to the user program when the call completes. 


If the value returned is positive, the result is the position of the first character of the pattern in the 
string. 


If the value returned is zero, the pattern was not found. 


If the value returned is negative, one of the following errors occurred: 
-1 The pattern is longer than the string. 
-2 The pattern length is less than 1. 
-3 The first character of the pattern is a wildcard character. 
-4 The pattern is blank and the trim trailing blanks parameter value is 1. 


-5 The starting position within the string is not valid. 


API existed prior to V3R1 


Top | Program and CL Command APIs | APIs by category 


Start Preprocessor (QbnStartPreProcessor) 
API 


Required Parameter: 


Error code 


Default Public Authority: *USE 


Service Program: QBNPREPR 


Threadsafe: No 


The Start Preprocessor (QbnStartPreProcessor) API must be called first by every compiler preprocessor that 
has data to be processed during module creation. This API must be called prior to calling the 
QbnAddAssociatedSpaceEntry, QbnAddExtendedAttributeData, QbnAddPreProcessorLevelData, or 
QbnAddBindtimeExit API. A call to the QbnEndPreProcessor API is the last API to be called during a 
single preprocessor call. 


Authorities and Locks 


None 


Required Parameter 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 


CPF5D28 E Not able to start preprocessing. 


API Introduced: V3R1 


Top | Program and CL Command APIs | APIs by category 


Store Program Associated Space (QCLSPGAS) 
API 


Required Parameter Group: 


Input data buffer Char(*) 
Length of input data buffer Binary(4) 
Qualified program name Char(20) 
Call stack counter Binary(4) 
Data handle Char(16) 
Error code Char(*) 


Default Public Authority: “EXCLUDE 


Threadsafe: No 


The Store Program Associated Space (QCLSPGAS) API allows you to store information in the associated 
space of an original program model (OPM), user-state program in the user domain. This API is intended to 
be used only on programs created by the Create Program (QPRCRTPG) API. 


This API's primary use is to store information about a program object for later use. For example, it can be 
used by a compiler to store information about the compilation process that is needed later at run time. The 
space associated with a program object is not a replacement for data areas or user spaces. It is 
recommended for static data only. 


There is no capability to delete the information after it is stored. Multiple store requests using the same data 
handle will write over any information previously stored. 


Authorities and Locks 


Program Library Authority 
*USE 

Program Authority 
*ALL 

Program Lock 
*EXCL 


Required Parameter Group 


Input data buffer 
INPUT; CHAR(*) 


The information to store in the associated space. This information can contain scalar data only. If it 


does contain pointer data, the pointer data is not kept. 
Length of input data buffer 
INPUT; BINARY(4) 
The length of the data in the input data buffer, in bytes. The maximum size of an associated space 


is 1OMB. An error is returned if the length of the input data and the data already stored in the 
associated space exceeds 16MB. 


Qualified program name 
INPUT; CHAR(20) 
The program object for which you want to store data in the associated space. This must be an OPM, 
user-state program in the user domain. An error is returned if the program is an ILE program, or if 


it is a system-state or system-domain program. The first 10 characters contain the program name, 
and the second 10 characters contain the library name. 


You can use the following special value for the program name: 


* A program in the call stack. The call stack counter contains the number of programs up the 
stack from the calling program to look for the program where the data is to be stored. 


You can use the following special values for the library name: 
*CURLIB The job's current library 


*LIBL The library list 


Call stack counter 
INPUT; BINARY(4) 


A number greater than zero identifying the location in the call stack for the program if * is specified 
for the program name. This number is relative to the program that called this API. This parameter is 
ignored if the program name is not *. 


Data handle 
INPUT; CHAR(16) 
The identifier to store the information under in the associated space. This identifier can be any 
unique value you choose to store your information under. You must remember this value if you 


want to later retrieve this information. Data may have been stored under a data handle. If this API is 
called to store data under it, the existing data is overwritten with the new data. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Error Messages 


Message ID 
CPF0301 E 
CPF0302 E 
CPF0303 E 
CPF0304 E 
CPF24B4 E 
CPF3C90 E 
CPF3CF1 E 
CPF8100 E 
CPF9803 E 
CPF9807 E 
CPF9808 E 
CPF9810 E 
CPF9811 E 
CPF9820 E 
CPF9821 E 
CPF9830 E 
CPF9838 E 
CPF9872 E 


Error Message Text 

Length of data buffer is not valid. 

Value for call stack counter not valid. 

Limit of associated space size exceeded. 

Operation not allowed for program &1 in library &2. 
Severe error while addressing parameter list. 

Literal value cannot be changed. 

Error code parameter not valid. 

All CPF81xx messages could be returned. xx is from 01 to FF. 
Cannot allocate object &2 in library &3. 

One or more libraries in library list deleted. 

Cannot allocate one or more libraries on library list. 
Library &1 not found. 

Program &1 in library &2 not found. 

Not authorized to use library &1. 

Not authorized to program &1 in library &2. 

Cannot assign library &1. 

User profile storage limit exceeded. 


Program or service program &1 in library &2 ended. Reason code &3. 
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Command Analyzer Change Exit Program 


Required Parameter Group: 


Change command exit information Input Char(*) 
Replacement command Output Char(*) 
Length of replacement command string Output Binary(4) 


QSYSINC Member Name: ECACHCMD 
Exit Point Name: QIBM_QCA_CHG_COMMAND 


Exit Point Format Name: CHGC0100 


The Command Analyzer Change exit program is called when the command for which it is registered is 
processed. The command analyzer calls the Change Command exit program for a command once through 
the registration facility before performing any of the following steps: 


e Prompting the command, 
e Performing interparameter checks, 
e Calling the validity checking program, and 


e Transferring control to the command processing program. 


The exit program is not called if the command analyzer was called to syntax check the command, but not 
run it. The exit point supports one change command exit program for each command. 


The exit program is called, but the command cannot be changed if any of the following occur: 
e The command was qualified with a specific library name. 


e The command has a parameter defined as RTNVAL(*YES), which allows the command processing 
program (CPP) to return a value to the calling program. 


e The user specified a parameter that shows no value in the job log. Those parameters are defined as 
DSPINPUT(*NO) or DSPINPUT(*PROMPT). 


e The command was used in a program running in system state. 


If changing the command is allowed, the exit program can change the command string so that the command 
analyzer processes a command from a different library or a completely different command. It also can 
change any or all of the parameters specified on the command. When a changed command string is returned 
to the command analyzer, the command analyzer will not prompt the replaced command or call the validity 
checking program, any exit programs registered for the QIBM_QCA_RTV_COMMAND exit point, or the 
command processing program for the replaced command. The command analyzer will start over with the 
changed command instead of the original one. It will do a full validation of the new command, including 
prompting if prompting was requested for the replaced command. If the changed command string specifies 
a different command in a different library and there is an exit program registered for the 
QIBM_QCA_CHG_COMMAND exit point for the new command, it will be called, but it will not be 
allowed to change the command. Exit programs registered for the QIBM_QCA_RTV_COMMAND exit 
point for the new command will be called. If the command is not changed, the command analyzer will 
continue with normal processing of the original command, including calling any exit programs registered 
for the QIBM_CA_RTV_COMMAND exit point. 


The replaced command string will be logged to the job log only when the original command was logged. 
For commands entered on a command line, the original command will be logged as a request message, and 
the substitute will be logged as a command message. This will allow users to retrieve their original 
command with the Retrieve function key. 


If the exit program sends any escape messages to the command analyzer, the message will be left in the job 

log and ignored by the command analyzer. The command analyzer will continue processing the original 

command. 

Exit programs may not be registered for the following system commands: 
e CALLPRC 

CHGVAR 

CNLRCV 

COPYRIGHT 

DCL 

DCLDTAARA 

DCLF 

DO 

ENDDO 

ENDPGM 

ENDRCV 

GOTO 

IF 

MONMSG 

PGM 

RCVDTAARA 

RCVF 

RETURN 

SNDF 

SNDRCVF 

TFRCTL 

WAIT 


In addition, exit programs may not be registered for these commands: 
e CALL command. 
e Commands that are restricted to use by the CL compiler when compiling for a previous release. 
e Commands in libraries QSYS38 and QUSER38. 
If the exit program uses the registered CL command, a recursive loop may occur. Recursive loops may also 


occur if two or more exit programs use each other's CL commands. For example, if the exit program for 
CMDA uses CMDB and the exit program for CMDB uses CMDA, a recursive loop will occur. 


Authorities and Locks 


You must have *ALLOBJ and *SECADM special authorities to register an exit program for the 
QIBM_QCA_CHG_COMMAND exit point. 


Required Parameter Group 


Change command exit information 
INPUT; CHAR(*) 


Information about the command that the command analyzer was called to process. 

Replacement command 
OUTPUT; CHAR(*) 
A string containing the command string that is to be substituted for the one the command analyzer 
was called to process. This will be ignored if the command is not allowed to be changed. The 
maximum length of the changed command string is 32000 bytes. 
Commands that should not be specified as the replacement command by an exit program include: 


o System commands that are used only in CL programs. See the list of system commands. 


o Commands that have a parameter that is used as a return value (RTNVAL(*YES)). 


o Commands that are restricted to use by the CL compiler when compiling for a previous 
release. 


If any of these commands are used as replacement commands, the command analyzer will send a 
diagnostic message, followed by escape message CPFO001, and processing of the command will 
end. 


Length of replacement command string 
OUTPUT; BINARY(4) 


The length of the replacement command string (0 - 32000) in bytes. If the length is 0, the original 
command string will be run, and the replacement command will be ignored. 


CHGC0100 Format 


The following table shows the format of the information supplied to a change command exit program. For a 
description of the fields in this format, see Field Descriptions. 


| Offset 
ee Hex |Type Field 


00 CHAR) kt pit 


Field Descriptions 


Change allowed indicator. Whether or not the exit program is allowed to change the command string that 
will be run. See the conditions where change is not allowed. Possible values are: 


I The command may be changed. 


0 The command may not be changed. 


If a replacement command is returned to the command analyzer, it will be ignored. 

Command name. The name of the command that is being processed. 

Command string. The command string that the command analyzer is processing. The command name will 
be library qualified, and the parameter values will be enclosed in parentheses and preceded by the keyword 
names. Any parameter that was defined as DSPINPUT(*NO) or DSPINPUT(*PROMPT) when the 
command was created will be formatted without the parameter value (for example, "PASSWORD()") to 
prevent the exit programs from getting passwords and similar secure data. This command string may not be 
correct syntactically because required parameters may be missing, interparameter checking has not been 
done, and the validity checking program for the command has not been called. 

Exit point name. The name of the exit point that calls the exit program. 


Exit point format name. The format name for the Change Command exit program. The possible format 
name is: 


CHGCO0100_ The format name that is used to supply the exit information. 


Length of command string. The length of the command string being processed. 

Library name. The name of the library for the command being processed. 

Offset to command string. The offset to the beginning of the command string. 

Prompt indicator. Whether prompting was requested on the original command string. Possible values are: 
O Prompting was not requested for the original command. 


I Prompting was requested for the original command. 


Reserved. Reserved area. 


Usage Notes 
Registration considerations. 


Use the Add Exit Program command (ADDEXITPGM) or API (QUSADDEP, QusAddExitProgram) to 
register an exit program for a command. You must specify 20 bytes of exit program data. The first 10 
characters specify the command name; the second 10 characters specify the library name. 


Any exit programs registered for commands in library QSYS also will be called for commands in the 
secondary language libraries. For example, if an exit program is registered for the DSPJOB command in 
library QSYS, it will also be called for the DSPJOB command in library QSYS2962. 


If you rename the command or the library or move the command to another library, you also must have an 
exit program registered using the new command and library names. 


Only one exit program can be registered for each command for the QIBM_QCA_CHG_COMMAND exit 
point. If two applications on the same system, however, need to replace the same command, they can do it 
by registering a single exit program, which replaces the command with one that is qualified with *LIBL 
instead of replacing it with their own specific commands. The QCARPLCM program in library QSYS may 
be used to do this. Applications using QCARPLCM must ensure that their application library is at the 
beginning of the system part of the library list. 


Any exit program registered for this exit point must be threadsafe if it will be called in a job that has 
multiple threads. 


Runtime considerations. 


This exit point is a command analyzer exit point that is called during the processing of individual 
commands. This does not imply that command usage by the system or by individual applications will not 
change or even be eliminated in the future. For example, if some system function, X, uses the CRTLIB CL 
command, you should not assume that X will always use the CRTLIB command. X's use of CL commands 
may change without any warning to use an API or some other interface. Therefore, you should not create 
any dependencies based on the assumption that a specific function is implemented using a CL command. 


If a command is qualified with special value *SYSTEM, only library QSYS will be searched for the 
command. The change exit program will be allowed to change the command. 


If a command is qualified with special value *NLVLIBL, only the national language version (NLV) 
libraries in the library list and QSYS will be searched for the command. The change exit program will be 
allowed to change the command. 


Adopted authority from previous call levels will be used to determine authority to the exit program, but will 
not be propagated to the exit program. The exit program will have all of the authorities available to the user 
profile under which the job is currently running; this may be a profile which has been swapped to, rather 
than the user profile under which a job was started. 


All users with at least *USE authority to the command also should have *OBJOPR and *EXECUTE 
authority to the exit program and *EXECUTE authority to the exit program's library. The command will 
fail if the user does not have sufficient authority to the exit program. 


Exit program introduced: V4R5 
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Command Analyzer Retrieve Exit Program 


Required Parameter Group: 


Retrieve command exit information Input 


QSYSINC Member Name: ECARTCMD 
Exit Point Name: QIBM_QCA_RTV_COMMAND 


Exit Point Format Name: RTVC0100 


The Command Analyzer Retrieve exit program is called when the command for which it is registered is 
processed. This program is called by the command analyzer through the registration facility immediately 
before transferring control to the command processing program. Exit programs will not be called if the 
command analyzer was called to syntax-check the command without running it. The exit point supports a 
maximum of ten retrieve rommand exit programs for each command. 


If the exit program sends any escape messages to the command analyzer, the message will be left in the job 

log and ignored by the command analyzer. 

Exit programs may not be registered for the following system commands: 
e CALLPRC 

CHGVAR 

CNLRCV 

COPYRIGHT 

DCL 

DCLDTAARA 

DCLF 

DO 

ENDDO 

ENDPGM 

ENDRCV 

GOTO 

IF 

MONMSG 

PGM 

RCVDTAARA 

RCVF 

RETURN 

SNDF 

SNDRCVF 


e TFRCTL 
e WAIT 


In addition, exit programs may not be registered for these commands: 
e CALL command 
e Commands that are restricted to use by the CL compiler when compiling for a previous release. 
e Commands in libraries QSYS38 and QUSER38. 


If the exit program uses the registered CL command, a recursive loop may occur. Recursive loops also may 
occur if two or more exit programs use each other's CL commands. For example, if the exit program for 
CMDA uses CMDB and the exit program for CMDB uses CMDA, a recursive loop will occur. 


Authorities and Locks 


You must have *ALLOBJ and *SECADM special authorities to register an exit program for the 
QIBM_QCA_RTV_COMMAND exit point. 


Required Parameter Group 


Retrieve command exit information 
INPUT; CHAR(*) 


Information about the command that the command analyzer was called to process. 


RTVC0100 Format 


The following table shows the format of the information supplied to a retrieve command exit program. For 
a description of the fields in this format, see Field Descriptions. 


[Offset 
a c | Hex |Type Field 


00 [CHAR — Jk pita 


Field Descriptions 


Command name. The name of the command that is being processed. 


Exit point format name. The format name for the Retrieve Command exit program. The possible format 
name is: 


RTVCOIOO The format name that is used to supply the exit information. 


Exit point name. The name of the exit point that calls the exit program 
(QIBM_QCA_RTV_COMMAND). 


Length of original command string. The length of the original command string being processed. 


Length of replacement command string. The length of the replacement command string from the user 
exit program that was called at exit point QIBM_QCA_CHG_COMMAND. This will be 0 if there is no 
exit program for exit point QIBM_QCA_CHG_COMMAND or if the exit program did not change the 
command. 


Library name. The name of the library of the command being processed. 
Offset to original command string. The offset to the beginning of the original command string. 


Offset to replacement command string. The offset to the beginning of the replacement command string. 
This will be 0 if there is no exit program for exit point QIBM_QCA_CHG_COMMAND or if the exit 
program did not change the command. 


Original command string. The command string that was originally submitted to the command analyzer for 
processing. The command name will be library qualified and the parameter values will be enclosed in 
parentheses and preceded by the keyword names. Any parameter that has DSPINPUT(*NO) or 
DSPINPUT(*PROMPT) will be formatted without the parameter value (for example, "PASSWORD()") to 
prevent exit programs from getting passwords and similar secure data. If the original command string was 
replaced by an exit program called at the QIBM_QCA_CHG_COMMAND exit point, this may not be 
syntactically correct because required parameters may be missing, interparameter checks have not been 
done, and the validity checking program has not been called. 


Replacement command string. The replacement command string from the user exit program that was 
called at exit point QIBM_QCA_CHG_COMMAND. The command name will be library qualified and the 
parameter values will be enclosed in parentheses and preceded by the keyword names. 


Reserved. Reserved area. 


Usage Notes 
Registration considerations. 


Use the Add Exit Program command (ADDEXITPGM) or the Add Exit Program (OPM, QUSADDEP; 
ILE, QusAddExitProgram) API to register an exit program for acommand. You must specify 20 bytes of 
exit program data. The first 10 characters specify the command name; the second 10 characters specify the 
library name. Any exit programs registered for commands in QSYS also will be called for commands in the 
secondary language libraries. For example, if an exit program is registered for the DSPJOB command in 
library QSYS, it will also be called for the DSPJOB command in library QSYS2962. 


If you rename the command or the library or move the command to another library, you must have an exit 
program registered for the new command and library names. 


Any exit program registered for this exit point must be threadsafe if it will be called in a job that has 
multiple threads. 


This exit point is a command analyzer exit point that is called during the processing of individual 
commands. This does not imply that command usage by the system or by individual applications will not 
change or even be eliminated in the future. For example, if some system function, X, uses the CRTLIB CL 
command, you should not assume that X will always use the CRTLIB command. X's use of CL commands 
may change without any warning to use an API or some other interface. Therefore, you should not create 
any dependencies based on the assumption that a specific function is implemented using a CL command. 


Runtime considerations. 


If a command is qualified with special value *SYSTEM, only library QSYS will be searched for the 
command. 


If a command is qualified with special value *NLVLIBL, only the national language version (NLV) 
libraries in the library list and QSYS will be searched for the command. 


Adopted authority from previous call levels will be used to determine authority to the exit program, but will 
not be propagated to the exit program. The exit program will have all of the authorities available to the user 
profile under which the job is currently running; this may be a profile which has been swapped to, rather 
than the user profile under which a job was started. 


All users with at least *USE authority to the command should also have *OBJOPR and *EXECUTE 
authority to the exit program and *EXECUTE authority to the exit program's library. The command will 
fail if the user does not have sufficient authority to the exit program. 


Exit program introduced: V4R5 


Top | Program and CL Command APIs | APIs by category 


